Configure the AI usage dashboard

Sigma provides an AI usage dashboard to monitor token consumption and interactions with all AI-powered features, including interactions with and usage of Sigma agents and Sigma Assistant.

Admins can configure the AI usage dashboard in AI settings.

Data security

AI usage data is visible on the AI usage dashboard, but only to users assigned the Admin account type. Unlike other usage dashboards, AI usage data is collected only if you configure it, and the data is stored in your data platform in a location that you specify.

Because AI usage data includes names of users and the full text of the questions they ask, Sigma recommends storing this data in a dedicated and secured location, granting view access only to the admins who need it.

The AI usage dashboard uses two schemas:

• Write destination schema: The schema where Sigma writes the underlying AI usage data. This is a write destination schema on the connection you select. If the connection has multiple write destination schemas, select the one where you want the table to exist. For example, a schema named SIGMA_WRITE_AI.
• AI usage schema: The schema you specify when you set up the dashboard. Sigma creates a view on top of the table stored here, so the data appears as an object in the connection browser in Sigma. For example, a schema named AI_USAGE.

Each schema has different permission requirements. For more information, see Connection access considerations.

Requirements

To set up the AI usage dashboard:

• You must be assigned the Admin account type.

• You must have permission to create a view in the AI usage schema using the table in the write destination schema. For example, the CREATE VIEW privilege on the AI_USAGE schema and the USAGE privilege on the SIGMA_WRITE_AI schema.

• You must have a Sigma connection to a supported data platform and have write access enabled.

  • Connect to Snowflake
  • Connect to Databricks
  • Connect to BigQuery

Connection access considerations

The credentials that Sigma users to write AI usage data to the write destination schema (for example, SIGMA_WRITE_AI) depends on how the connection you use to store the data is set up:

To track AI usage, you must grant write access to the write destination schema (for example, SIGMA_WRITE_AI) to the credentials used to track AI usage. If you do not grant write access to that schema, users can continue to use AI-powered features, but their usage is not logged to the AI usage table.

If your connection uses OAuth without a service account, choose one of the following options to limit which users must be granted write access privileges in your data platform:

• (Recommended) Add a service account to the OAuth connection, then grant write access privileges on the write destination schema only to the service account. To add a service account to an OAuth connection, see the documentation for your connection type:

  • Connect to Snowflake
  • Connect to Databricks
  • Connect to BigQuery

• Create a dedicated connection to your data platform to use only for usage tracking and grant all users Can write only access to the connection. For instructions, see the following:

  • Set up a connection to Snowflake with write access using key pair authentication and a specific role.
  • Set up a connection to Databricks with write access using basic authentication and a service principal.
  • Set up a connection to BigQuery with write access using basic authentication.

• Use the existing OAuth connection and set up a dedicated destination to use only for the AI usage dashboard and grant the relevant privileges only to that destination.

  For example, create a SIGMA catalog in Databricks, then create an AI_USAGE schema. Only grant MODIFY and CREATE TABLE privileges on that schema to users who have permission to use AI-powered features in Sigma.

Configure the AI usage dashboard

After setting up a connection with write access, configure the AI usage dashboard:

1. Go to Administration > AI settings:

   1. In the Sigma header, click your user avatar to open the user menu.
   2. Select Administration to open the Administration portal.
   3. In the side panel, select AI settings.

2. In the Chat history and usage data section, for Track AI usage, click Set up AI usage table.

3. For Connection, select a connection that has write access turned on.

4. Based on the type of connection that you add, complete the additional fields to specify the destination you created, matching the capitalization of the objects in your data platform:

   • For a BigQuery connection, specify a ProjectID and Dataset.
   • For a Databricks connection, specify a Catalog and Schema.
   • For a Snowflake connection, specify a Database and Schema.

5. Click Save.

   If you see an error “Cannot manage views on given scope with the following error: SQL access control error: Insufficient privileges to operate on schema ‘your_schema_name’”, the schema or dataset that you entered does not allow write access. Ensure that the write destination in your data platform is configured correctly.

   The table is created with a name like AI_USAGE_<ORGANIZATION_NAME>.

After creating the dashboard, you can review usage from the Usage dashboards. See Usage overview. To open the dashboard from AI settings, click Open the AI usage page in the Track AI usage section.

Edit or delete the AI usage table configuration

To change the location of the AI usage table or delete it:

1. Go to Administration > AI settings.

2. In the Chat history and usage data section, for Track AI usage, click Edit.

   • To change the location, update the connection and destination fields, then click Update. When prompted to confirm the new location, confirm the change.

     The existing AI usage table is deleted and an empty one is created at the new location.

   • To delete the AI usage table configuration, click Delete.

Migrate Assistant usage data to AI usage

If your data platform still contains historical data from the Assistant usage table, you can migrate it to the AI usage table. Because the Assistant usage dashboard is removed, you must look up the table locations directly in your data platform rather than from the dashboard.

System and user requirements

To migrate data:

• You must configure AI usage and the AI usage table must be set up on the same connection as the Assistant usage table.
• You must know the fully qualified locations of both the Assistant usage table and the AI usage table. Look up each location in your data platform: the Assistant usage table is named ASK_<ORGANIZATION_NAME> and the AI usage table is named AI_USAGE_<ORGANIZATION_NAME>, both in the schema you configured for each dashboard.
• You must be assigned the Admin account type.

Limitations

The data collected for the Assistant usage dashboard is in a different schema structure than the data collected for the AI usage dashboard, so the migration maps the columns as follows:

Copy Assistant usage data to the AI usage table

To copy historical Assistant usage data to the AI usage table:

1. Write INSERT SQL against the fully qualified locations of both tables.
2. Run the SQL in your data platform where you have the Assistant usage and AI usage dashboards configured.

Both the Assistant usage and AI usage tables are managed by Sigma. You must reference each table by its fully qualified location.

Because the Assistant usage dashboard is removed, you must find the locations of the tables directly in your data platform instead of copying them from the dashboard:

1. In your data platform, locate the table named ASK_<ORGANIZATION_NAME> in the schema you configured for the Assistant usage dashboard, and the table named AI_USAGE_<ORGANIZATION_NAME> in the schema you configured for the AI usage dashboard.

2. Note the fully qualified path to each table, for example:

   • DATABASE.SCHEMA.ASK_<ORGANIZATION_NAME>
   • DATABASE.SCHEMA.AI_USAGE_<ORGANIZATION_NAME>

To copy the data:

1. Write the INSERT SQL, replacing the placeholder values with the specifics for your organization.

   If you write your own SQL statement, your INSERT must also populate the following system columns in addition to the usage data columns:

   System column	Value
   ID	A unique 16-byte binary primary key for each row. Because QUESTION_ID is not unique, the example salts it with a row number.
   SEQ_NUM	A non-null, fixed-width ordered key so migrated rows sort consistently.
   ROW_VERSION	A non-null version number, seeded from the current maximum value in the AI usage table.
   UPDATED_BY	The email address to record as the editor of the migrated rows.
   UPDATED_AT	When the row was last updated. The example uses the original Assistant usage timestamp.

   Columns in the AI usage table are case-senstive and stored in lowercase. Treat each column as a delimited identifier. If you store your usage data in Databricks, wrap each column name with backticks. For example, trace_id.

2. In your data platform, run the SQL. Avoid running the SQL statement when AI-powered features are being used in Sigma to avoid duplicated data or conflicts.

If you store your Assistant usage data in a Snowflake connection, you can use the following example SQL. If you store Assistant usage data in Databricks or BigQuery, update the SQL statement to use the relevant primary key, sequencing, and JSON functions for your data platform.

Before running the example SQL, replace the following placeholder values:

• <AI_USAGE_TABLE_LOCATION>: The fully qualified location of the AI usage table.
• <ASSISTANT_USAGE_TABLE_LOCATION>: The fully qualified location of the Assistant usage table.
• <user@example.com>: The user email address to record in UPDATED_BY.

INSERT INTO <AI_USAGE_TABLE_LOCATION> (
  ID, SEQ_NUM, ROW_VERSION, UPDATED_BY, UPDATED_AT,
  "trace_id", "span_id", "parent_id", "span_type", "trace_name",
  "agent_name", "agent_id", "user_name", "session_id", "ai_provider",
  "model", "tokens_input", "tokens_output", "tags", "tool_calls",
  "input", "output", "metadata", "trace_created_at_utc"
)
WITH src AS (
  -- Number each source row so the primary key and sequence are unique and ordered.
  SELECT a.*, ROW_NUMBER() OVER (ORDER BY a."TIMESTAMP", a.QUESTION_ID) AS rn
  FROM <ASSISTANT_USAGE_TABLE_LOCATION> a
),
seed AS (
  -- Seed ROW_VERSION from the current maximum so migrated rows don't collide with existing rows.
  SELECT COALESCE(MAX(ROW_VERSION), 0) AS max_rv
  FROM <AI_USAGE_TABLE_LOCATION>
)
SELECT
  -- 16-byte binary primary key, unique per source row (QUESTION_ID is not unique, so salt with rn).
  MD5_BINARY(src.QUESTION_ID || '|' || src.rn::varchar)        AS ID,
  -- Non-null, fixed-width ordered key so migrated rows sort consistently.
  TO_BINARY(LPAD(src.rn::varchar, 20, '0'), 'UTF-8')           AS SEQ_NUM,
  seed.max_rv + src.rn                                         AS ROW_VERSION,
  '<your_email@example.com>'                                   AS UPDATED_BY,
  src."TIMESTAMP"                                              AS UPDATED_AT,
  src.QUESTION_ID                                              AS "trace_id",
  src.QUESTION_ID                                              AS "span_id",
  NULL                                                         AS "parent_id",
  'generation'                                                 AS "span_type",
  'ask-sigma'                                                  AS "trace_name",
  src.AGENT                                                    AS "agent_name",
  NULL                                                         AS "agent_id",
  src.USER_NAME                                                AS "user_name",
  NULL                                                         AS "session_id",
  NULL                                                         AS "ai_provider",
  src.MODEL                                                    AS "model",
  src.TOKENS                                                   AS "tokens_input",
  0                                                            AS "tokens_output",
  ARRAY_CONSTRUCT()                                            AS "tags",
  ARRAY_CONSTRUCT()                                            AS "tool_calls",
  OBJECT_CONSTRUCT('question', src.USER_QUESTION)              AS "input",
  OBJECT_CONSTRUCT('result', src.RESULT)                       AS "output",
  OBJECT_CONSTRUCT(
    'userId',             src.USER_ID,
    'dataClassification', src.DATA_CLASSIFICATION,
    'selectedSource',     src.SELECTED_SOURCE,
    'improvement',        src.IMPROVEMENT,
    'teams',              TRY_PARSE_JSON(src.TEAMS),
    'warehouseRuntimeMs', src.WAREHOUSE_RUNTIME_MS,
    'llmRuntimeMs',       src.LLM_RUNTIME_MS,
    'error',              src.ERROR,
    'callCount',          src.CALL_COUNT,
    'migratedFrom',       'ask_usage'
  )                                                            AS "metadata",
  src."TIMESTAMP"                                              AS "trace_created_at_utc"
FROM src CROSS JOIN seed;

Related resources

• AI usage dashboard
• Assistant usage dashboard (Removed)