--- url: 'https://docs.codatum.com/index.md' description: >- An overview of Codatum, which connects to a DWH to run, visualize, and share SQL, and a guide to the documentation --- # Introduction ## What is Codatum? Codatum is a data analytics platform for connecting to a data warehouse (DWH), running SQL, and analyzing, visualizing, and sharing the results. It supports BigQuery, Snowflake, Databricks, and Redshift. You do your analysis in a [notebook](./features/notebook/overview). Because SQL, charts, and text stay together in a single document, your team can share not just the numbers but also the logic behind them and how to interpret them. An [AI agent](./features/ai-agent/overview) can operate directly on your notebooks. From a natural language instruction, it runs SQL and creates charts, leaving the process as SQL in the notebook. It draws on descriptions and tags in the [catalog](./features/catalog/overview) and definitions accumulated in [agent context](./features/ai-agent/agent-context) to inform its analysis. ## What you can do with Codatum ### Analyze Write SQL in a [notebook](./features/notebook/overview) and bring the results together with charts and text in a single document. [SQL blocks](./features/notebook/doc-page/sql-block) support autocomplete and formatting, and you can build up SQL step by step by referencing SQL defined in other blocks (SQL chaining). [Parameters](./features/notebook/parameter/overview) let you change conditions like a date range or analysis target with ease. For standardized analyses such as funnel analysis or budget-vs-actual tracking, you can arrange charts on a [grid page](./features/notebook/grid-page/overview) to build a dashboard. For deep dives into changes in the numbers, use the [explorer](./features/notebook/explorer) to explore results through a GUI. ### Delegate to the AI agent Ask the [AI agent](./features/ai-agent/overview) a question in natural language, and it runs SQL and creates charts for you. Because the process is left as SQL in the notebook, you can review and adjust the output yourself. The agent draws on descriptions and tags added in the [catalog](./features/catalog/overview) and metric definitions placed in [agent context](./features/ai-agent/agent-context), enabling analysis that reflects internal terminology and calculation rules. You manage the model, permissions, and fixed context in an [AI profile](./workspace/codatum-ai/ai-profile). ### Share You can choose how to share your analysis results depending on the audience and purpose. Use a [report](./features/notebook/sharing/report/overview) for internal members and guests, a [public link](./features/notebook/sharing/public-link/overview) when you want to show results without requiring login, and a [signed embed](./features/notebook/sharing/signed-embed/overview) to embed results in your own SaaS product or internal tools. Reports can be viewed and re-run within the scope of the publish settings even without connection permissions. With signed embeds, you can use [fixed values for server-side parameters](./features/notebook/sharing/signed-embed/overview#server-side-params) to isolate the data each tenant can access. ### Run on a schedule Use a [workflow](./features/workflow/overview) to run [queries](./features/saved-query/overview) or reports on a schedule. You can connect the results to follow-up steps, such as delivering them to Slack or email, or summarizing them with an LLM. This is useful for things like daily KPI delivery or model monitoring. ### Organize and manage your data Register a [connection](./features/connection/overview) and configure which tables to sync, and the table and column metadata syncs to the [catalog](./features/catalog/overview). Adding [annotations](./features/catalog/annotation) (descriptions and tags) makes that metadata available for autocomplete, search, and the agent. [Permissions](./permissions/overview) are controlled through a combination of workspace roles and resource roles. Codatum also supports dividing work areas with [teamspaces](./workspace/administration/teamspace), granting permissions by [group](./workspace/administration/group), [audit logs](./workspace/access-and-security/audit-log), and [IP access control and MFA](./workspace/access-and-security/security). ### Operate from a terminal or CI With the [Codatum CLI](./features/cli/overview), you can treat notebooks as markdown files and catalog annotations as YAML files. This enables version control with git and operation from CI or coding agents. ## Documentation structure * [Guide](./guide/screen-layout) — Screen layout, global navigation, and more * Features — Explanations of the main features * [Quick search](./features/quick-search/overview) — Cross-search across notebooks, tables, and queries * [Connection](./features/connection/overview) — Data warehouse connection setup and metadata management * [Catalog](./features/catalog/overview) — Metadata management for tables and saved queries * [Query](./features/saved-query/overview) — Saved SQL reused within a connection * [Notebook](./features/notebook/overview) — Your workspace for data analysis, with collaborative editing, SQL, charts, and more * [Workflow](./features/workflow/overview) — Scheduled runs and automation * [AI agent](./features/ai-agent/overview) — Natural language analysis and notebook operation, and AI profiles * [AI Assistant](./features/ai-assistant/overview) — A chat for creating SQL and charts and answering questions (deprecated; new provisioning discontinued) * [Codatum CLI](./features/cli/overview) — A CLI for operating Codatum from the terminal * [Workspace](./workspace/overview) — The management unit, users, invitations, API keys, and more * [Permissions](./permissions/overview) — The permission model and permissions for each resource * [Account](./account/overview) — Accounts, sign-up, and account settings * [Reference](./reference/glossary) — [Glossary](./reference/glossary), [Limits](./reference/limits), [System requirements](./reference/requirements) --- --- url: 'https://docs.codatum.com/guide/screen-layout.md' description: >- The regions that make up the Codatum screen (global nav, header, left sidebar, main area, right sidebar) --- # Screen layout After you log in, the screen is made up of the following regions. This documentation uses these names when referring to positions on the screen. ![Screen layout: global nav, header, left sidebar, main area, right sidebar](/images/screen-layout-en.svg) Depending on the feature or screen, only some of these regions might be shown. Even if a region isn't shown, the positions of the other regions follow this layout. ## Regions {#regions} | Region {.nowrap} | Position | Description | | --- | --- | --- | | [Global nav](#global-nav) | Left edge of the screen | Entry points to the main features and settings | | [Header](#header) | Top of the screen | The screen title, action buttons, and more | | [Left sidebar](#left-sidebar) | Left of the main area | Lists, trees, filters, and more | | [Main area](#main-area) | Center of the screen | The main content for that screen | | [Right sidebar](#right-sidebar) | Right of the main area | Detail information, auxiliary panels, and more | ## Global nav {#global-nav} The region at the left edge of the screen. It provides workspace switching and entry points to the main features and settings. For the menu structure, see [Navigation](./navigation). ## Header {#header} The region at the top of the screen, to the right of the global nav. It holds the title of the open resource, action buttons, and similar controls. ## Left sidebar {#left-sidebar} The region below the header, to the left of the main area. It shows things like a folder tree or filters, mainly to let you choose what's shown in the main area. ## Main area {#main-area} The region at the center of the screen. It shows the main content for that screen, such as the body of a notebook, a list, or a settings form. ## Right sidebar {#right-sidebar} The region to the right of the main area. It shows detail information, auxiliary panels, and similar content. It might be closed, or might not exist at all, depending on the feature. --- --- url: 'https://docs.codatum.com/guide/navigation.md' description: The global nav menu structure and how it leads to each feature --- # Navigation After you log in to Codatum, the [global nav](./screen-layout) at the left edge of the screen takes you to the main features and settings. For the names of the screen regions, see [Screen layout](./screen-layout). The global nav is split into a top and bottom section, each with the following entry points. * [Top](#nav-top): Workspace switching and entry points to the main features * [Bottom](#nav-bottom): Entry points to workspace settings, help, and account settings ## Global nav top {#nav-top} | Item {.nowrap} | Description | | --- | --- | | [(workspace icon)](#workspace-icon) | Lets you switch workspaces and perform other workspace-related actions | | Notifications | A dot appears when you have unread notifications | | [Quick search](../features/quick-search/overview) | Search across notebooks, tables, queries, and more | | [AI agent](../features/ai-agent/overview) | Goes to the AI agent's full-screen page | | [Notebook](../features/notebook/overview) | Goes to the notebook list | | [Query](../features/saved-query/overview) | Goes to the query list | | [Catalog](../features/catalog/overview) | Goes to the catalog list | | [Workflow](../features/workflow/overview) | Goes to the workflow list | | [Report](../features/notebook/sharing/report/overview) | Goes to the report list | ::: tip To get to [**Connections**](../features/connection/overview), open **Workspace settings** at the bottom of the global nav, then select **Data management** > **Connections** in the left sidebar. ::: ### Workspace icon {#workspace-icon} The workspace icon at the top of the global nav lets you do the following. | Item {.nowrap} | Description | | --- | --- | | (name of the current workspace) | Switches the workspace you're working in. If you belong to multiple workspaces in the same organization, those are grouped under the organization name. Other workspaces are grouped under the **Workspace** subheading | | **Browse all** | Goes to the **workspace selection screen**. In addition to a list of the workspaces you belong to, you can **create a new organization, join a workspace you've been invited to, join a workspace through an [allowed domain](../workspace/administration/invite#allowed-domains), or join or decline an [organization owner invitation](../workspace/administration/organization#invitee-flow)**. If you belong to multiple workspaces in the same organization, those are grouped under the organization name. Other workspaces are grouped under the **Workspace** subheading | ## Global nav bottom {#nav-bottom} | Item {.nowrap} | Description | | --- | --- | | [AI Assistant](../features/ai-assistant/overview) | Opens AI Assistant | | [Workspace settings](../workspace/overview) | Goes to the workspace settings for the workspace you're working in | | Help | Chat support, Product updates, Feedback board, [Docs](https://docs.codatum.com), [CLI Docs](https://cli-docs.codatum.com), Online support, [System status](https://status.codatum.com) | | [(avatar icon)](../account/overview#account-settings) | Account settings, [Organization settings](../workspace/administration/organization) (organization owners only), Sign out, Switch theme, Switch language | --- --- url: 'https://docs.codatum.com/features/quick-search/overview.md' description: 'Search across notebooks, tables, and queries' --- # Quick search Quick search lets you search across resources in your workspace. Select **Quick search** in the [global nav](../../guide/screen-layout). ## Key features * Full-text search for notebooks (notebook name and body content, including SQL) * Table search (name, schema information, and descriptions/tags added in the catalog) * Query search (name, schema information, and descriptions/tags added in the catalog) --- --- url: 'https://docs.codatum.com/features/connection/overview.md' description: >- Connection settings for your warehouse, and the unit for running SQL and syncing metadata --- # Connection A connection manages access to a data warehouse. It uses the credentials you register to run SQL and fetch table information. You can create and edit connections from [global nav](../../guide/screen-layout) > **Workspace settings** > **Data management** > **Connections**. To check synced tables, use the [catalog](../catalog/overview). ## Key features * Running SQL: Notebooks, reports, and saved queries can all run SQL using the registered credentials. * Aggregating metadata: [Table metadata sync](../catalog/metadata-sync) syncs table schemas and other metadata to the catalog. * Permissions: [Access level](#access-level) and resource roles control who can run SQL and retrieve results. For resource role details, see [Connection permissions](../../permissions/resources/connection). * Supported warehouses: [BigQuery](./warehouses/bigquery) / [Snowflake](./warehouses/snowflake) / [Redshift](./warehouses/redshift) / [Databricks](./warehouses/databricks). * Codatum is adding support for more warehouses over time. To request a connection to a warehouse not listed above, contact Codatum support. * [Demo connection](#demo-connection): A sample connection you can use to try the product before setting up your own warehouse. * [Job label](./job-label): Metadata that identifies where SQL was issued from (added automatically). ## Creating and managing connections 1. Open [global nav](../../guide/screen-layout) > **Workspace settings** > **Data management** > **Connections**. 2. Select a warehouse from **New connection**. 3. Enter **Connection name**, **Access level**, and the connection settings for the warehouse. 4. Run **Test connect** to verify connectivity, then select **Save**. The list is split into the following sections. * **Available connections**: Connections you can use. * **Restricted Connections**: Connections you don't have access to. If you can edit permissions, select **Edit permissions** to grant access. The maximum number of connections depends on your contract ([Limits](../../reference/limits#plan-limits)). ## Detail screen The detail screen lets you check and operate the following. * **View on catalog**: Opens the [catalog](../catalog/overview) filtered to this connection. * **General**: Edit the name and connection options (not available for the demo connection). * **Access level and permissions**: Check and edit the access level and resource roles. * **Query jobs**: The query job history for this connection (**View history** / **Last run**). This is a separate entry point from the **Query jobs** tab on the table/query detail in the catalog. * **Table sync settings**: **Last sync job**, **Sync targets**, **Resync Immediately**, and **Sync history**. See [Table metadata sync](../catalog/metadata-sync) for details. * **Danger zone**: **Delete connection** (also deletes related catalog data and saved queries). ## Demo connection {#demo-connection} The demo connection is a sample connection you can use to try out Codatum's features. * You can experience Codatum's features before setting up your own warehouse. * It includes typical business data (sales, customers, products, and so on). * You can immediately run SQL against the demo connection when creating a notebook or report. | Item {.nowrap} | Value | | --- | --- | | Connection name | `Demo Connection` | | Type | BigQuery | | Access level | Workspace | | Editing | You can't edit the general settings or sync targets | | Deletion | You can delete it like any other connection | The sync targets are fixed (a sample dataset provided by Codatum and some public BigQuery datasets). You can't change the sync targets manually. ## Access level {#access-level} You select the access level when you create a connection. The default is **Workspace**. **Protected** and **Private** might not be available, depending on your contract. For the meaning of each access level and the operations allowed for each resource role, see [Connection permissions](../../permissions/resources/connection#access-level). You can add up to 3 Connection Owners to a regular connection ([Limits](../../reference/limits#fixed-limits)). --- --- url: 'https://docs.codatum.com/features/connection/warehouses/bigquery.md' description: Setting up a BigQuery connection --- # BigQuery Connect Codatum to BigQuery to run SQL and manage data. For an overview of connections in general, see [Connection](../overview). ## Preparing BigQuery Prepare a service account and service account key, and grant it the roles (or equivalent permissions) it needs on the target project and dataset. | Grant on {.nowrap} | Role (or equivalent permission) | | --- | --- | | Project | `BigQuery Job User` (or `bigquery.jobs.create`) | | Project | `BigQuery Read Session User` (or `bigquery.readsessions.create` / `getData` / `update`) | | Dataset | `BigQuery Data Viewer` (or `bigquery.tables.getData` / `bigquery.datasets.get` / `bigquery.tables.get` / `bigquery.tables.list`) | (Optional) To sync dataset and table information without entering a project ID, grant `resourcemanager.projects.get` on the target project. Note the target **Project ID** for later use. ## Configuring Codatum 1. Open global nav > **Workspace settings** > **Data management** > **Connections**, then select **New connection**. 2. Select **Google BigQuery**. 3. Enter a **Connection name**. 4. Select an **Access level**. 5. Upload the service account key under **JSON key file** > **File upload** (Client Email is filled in automatically from the JSON). 6. Enter the **Project ID** (the JSON's `project_id` might be filled in as a default; you can change it manually). 7. Run **Test connect**, then save the connection. 8. On the sync targets screen shown after saving, select the datasets to sync ([Table metadata sync](../../catalog/metadata-sync#sync-target)). You can also skip this step. --- --- url: 'https://docs.codatum.com/features/connection/warehouses/snowflake.md' description: Setting up a Snowflake connection (key pair authentication) --- # Snowflake Connect Codatum to Snowflake to run SQL and manage data. For an overview of connections in general, see [Connection](../overview). ## Preparing Snowflake 1. Create a key pair and set the public key on the Snowflake user you'll use for the connection (see Snowflake's [key pair authentication guide](https://docs.snowflake.com/en/user-guide/key-pair-auth)). 2. Grant the following privileges to the role assigned to the user: * Warehouse: `USAGE` * Database: `USAGE` * Schema: `USAGE` * Table: `SELECT` ## Configuring Codatum 1. Open global nav > **Workspace settings** > **Data management** > **Connections**, then select **New connection**. 2. Select **Snowflake**. 3. Enter a **Connection name**. 4. Select an **Access level**. 5. Enter the following. | Item | Description | | --- | --- | | Organization name | The name of your Snowflake organization (see [account identifier](https://docs.snowflake.com/en/user-guide/admin-account-identifier#label-account-name-find)) | | Account name | The name of your Snowflake account (don't confuse this with the full account identifier, which includes the organization name) | | Username (login name) | The login name of the user you prepared | | Role | The name of the role you prepared | | Warehouse name | The name of the warehouse you prepared | | Database name | The default database used when statements run (this doesn't limit which tables or schemas can be referenced in SQL) | | Authentication method | `Key-pair authentication` (currently the only option) | | Private key | The entire private key, including `-----BEGIN PRIVATE KEY-----` through `-----END PRIVATE KEY-----` | | Passphrase (if the private key is encrypted) | Enter only if the private key is encrypted | After entering these, run **Test connect**, then save the connection. On the sync targets screen shown after saving, select the databases/schemas to sync ([Table metadata sync](../../catalog/metadata-sync#sync-target)). You can also skip this step. ## Network Codatum **doesn't provide a fixed IP address** for connections. If your Snowflake setup requires IP allowlisting, contact Codatum support. --- --- url: 'https://docs.codatum.com/features/connection/warehouses/redshift.md' description: Setting up an Amazon Redshift connection --- # Redshift (Preview) Connect Codatum to Redshift to run SQL and manage data. Supported targets are **RA3 node clusters** and **serverless**. For an overview of connections in general, see [Connection](../overview). ::: info This feature is in **preview**. To request access, contact Codatum support. ::: ## Preparing AWS * DB: Grant the integration role `USAGE` on the schema, `SELECT` on the tables, and `SELECT` on `svv_table_info`. * IAM: Grant `AmazonRedshiftFullAccess` to the integration IAM user. * Secrets Manager: Create a secret for the connection target and add the `RedshiftDataFullAccess` tag (the value can be empty). ## Configuring Codatum 1. Open global nav > **Workspace settings** > **Data management** > **Connections**, then select **New connection**. 2. Select **Amazon Redshift** (only shown if it's available to you). 3. Enter a **Connection name** and select an **Access level**. 4. Enter the following. | Item {.nowrap} | Description | | --- | --- | | Account ID | Your AWS account ID | | Region | The region of your Redshift resources | | Connection type | **Cluster** or **Serverless** (default is cluster) | | Cluster identifier | When the connection type is cluster | | Serverless namespace | When the connection type is serverless | | Serverless workgroup name | When the connection type is serverless | | Default database | The database to connect to (this doesn't limit which SQL you can run) | | AWS access key ID | The access key ID of the IAM user | | AWS secret access key | The secret access key of the IAM user | | Secret ARN | The ARN of the secret in Secrets Manager | After entering these, run **Test connect**, then save the connection. On the sync targets screen shown after saving, select the databases/schemas to sync ([Table metadata sync](../../catalog/metadata-sync#sync-target)). You can also skip this step. --- --- url: 'https://docs.codatum.com/features/connection/warehouses/databricks.md' description: Setting up a Databricks connection --- # Databricks (Preview) Connect Codatum to Databricks to run SQL and manage data. Supported targets are **serverless SQL warehouses**. For an overview of connections in general, see [Connection](../overview). ::: info This feature is in **preview**. To request access, contact Codatum support. ::: ## Preparing Databricks ### Account console * Create a service principal for the integration under User management > Service principals. * Generate an OAuth secret under Credentials & secrets, and note the client ID/secret. * Leave all role settings for the service principal turned off. * Add the service principal to the workspace you're connecting to. ### Workspace admin console * Grant the service principal `Can Use` on the SQL warehouse you're connecting to. * Grant `SELECT` / `USE CATALOG` / `USE SCHEMA` on the catalog. ## Configuring Codatum 1. Open global nav > **Workspace settings** > **Data management** > **Connections**, then select **New connection**. 2. Select **Databricks**. 3. Set a **Connection name** and **Access level**. 4. Enter the following. | Item {.nowrap} | Description | | --- | --- | | Server hostname | The hostname from the SQL warehouse's connection details (for example, `.cloud.databricks.com`) | | HTTP path | The HTTP path from the SQL warehouse's connection details (for example, `/sql/1.0/warehouses/`) | | Warehouse ID | The ID from the SQL warehouse's overview | | Client ID | The client ID of the service principal | | Client secret | The client secret of the service principal | After entering these, run **Test connect**, then save the connection. On the sync targets screen shown after saving, select the databases/schemas to sync ([Table metadata sync](../../catalog/metadata-sync#sync-target)). You can also skip this step. --- --- url: 'https://docs.codatum.com/features/connection/job-label.md' description: Metadata that identifies the source of SQL on the warehouse side --- # Job label (Beta) Codatum attaches metadata to the SQL it issues to your warehouse, identifying the source (which notebook, report, saved query, or signed embed the SQL ran from). There's no setting for this on the connection screen; it's added automatically at execution time. ::: info This feature is in **beta**. The specification might change without notice. ::: ## What's included and excluded * **Included**: Cell execution in a notebook, saved queries, reports, signed embeds, and ad hoc SQL runs from the [Codatum CLI](../cli/overview), AI Agent, and similar sources. * **Excluded**: Internal metadata retrieval (dry runs, schema fetches, data previews, and so on). ## Source priority Only **one** primary source ID is attached. The priority is: **Report** > **Signed embed** > **Notebook** > **Saved query** When run from a report, the report ID is attached instead of the notebook ID. If none of these IDs apply, the value is `unknown`. ## BigQuery (job labels) | Label key | Value | | --- | --- | | `source` | Always `codatum` | | `cdm_source_type` | `notebook` / `query` / `report` / `signed_embed` / `unknown` | | `cdm__id` | Primary source ID (for example, `cdm_notebook_id` / `cdm_report_id`) | | `cdm_workspace_id` | Workspace ID | | `cdm_connection_id` | Connection ID | | `cdm_actor_type` | `user` / `workflow` / `api_key` / `admin` / `system` (BigQuery label values are lowercase) | You can reference these from the labels in `INFORMATION_SCHEMA.JOBS`. ```sql SELECT job_id, creation_time, total_bytes_billed, (SELECT value FROM UNNEST(labels) WHERE key = 'cdm_source_type') AS source_type, (SELECT value FROM UNNEST(labels) WHERE key = 'cdm_notebook_id') AS notebook_id, (SELECT value FROM UNNEST(labels) WHERE key = 'cdm_report_id') AS report_id FROM `region-us`.INFORMATION_SCHEMA.JOBS WHERE creation_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY) AND EXISTS (SELECT 1 FROM UNNEST(labels) WHERE key = 'source' AND value = 'codatum') ``` Change `region-us` to match the region of the target dataset. ## Snowflake (QUERY\_TAG) Codatum attaches equivalent source information as a **QUERY\_TAG** (JSON). Reference the `QUERY_TAG` column in `QUERY_HISTORY`. | Key | Value | | --- | --- | | `source` | Always `codatum` | | `source_type` | `notebook` / `query` / `report` / `signed_embed` / `unknown` | | `notebook_id` / `query_id` / `report_id` / `signed_embed_id` | Primary source ID (only one is present) | | `workspace_id` | Workspace ID | | `connection_id` | Connection ID | | `actor_type` | The type of actor that ran the query (for example, `USER`). Uppercase in Snowflake / SQL comments | ## Redshift / Databricks (leading SQL comment) Codatum attaches this as a leading comment on the SQL it runs. Reference it from the SQL text in the run history. Example format: ```sql /* codatum source_type=notebook notebook_id=... workspace_id=... connection_id=... actor_type=USER */ SELECT ... ``` The keys have the same meaning as the Snowflake QUERY\_TAG. ## Use cases * Table inventory: Mechanically determine which notebooks or reports reference which tables. * Cost analysis: Identify expensive or slow SQL, then trace it back to the notebook or report that issued it. --- --- url: 'https://docs.codatum.com/features/catalog/overview.md' description: Manage metadata for tables and saved queries --- # Catalog The catalog lets you view lists and details of tables and saved queries, and add descriptions and tags to them. Open it from [global nav](../../guide/screen-layout) > **Catalog**. Table metadata comes from [connections](../connection/overview). There's no dedicated resource role for the catalog. Viewing and editing follow the permissions of the related connection. See [Catalog](../../permissions/resources/catalog) for details. ## Key features * [Table metadata sync](./metadata-sync): Syncs table and column metadata from connections, updated on a schedule or manually. * [Annotations](./annotation): Add descriptions and tags to tables and columns. * [Popularity and references](#popularity-and-references): Check popularity based on query jobs, and reference relationships. * [Filtering and search](#search-filters): Filter the list by common filters, connection, or search keys. * [Creating notebooks/queries](#create-from-catalog): Create a notebook or saved query from the catalog. ## Screen layout Switch between **Tables** and **Queries** in the [left sidebar](../../guide/screen-layout). * **Tables**: List and details of synced tables. * **Queries**: List and details of saved queries. The left sidebar also lets you set the following filters. * **Common filters**: **Starred** (starred items only). The query side also has **Created by me**. * **Connections**: Filter by connection. Select **Manage connections** to go to the [connection](../connection/overview) settings screen. ### Table detail Opening a table shows the following tabs. | Tab {.nowrap} | Contents | | --- | --- | | **Overview** | Connection, structure, description, type, tags, storage information, and dates | | **Columns** | Column list. You can edit descriptions and tags | | **Preview** | A preview of the table data (up to 100 rows; see [Limits](../../reference/limits#fixed-limits)) | | **References** | Referencing notebooks / referencing queries | | **Query jobs** | Query jobs that referenced this table | | **Other** | Definition, data location, view query, partitioning, and other retrieved items | ### Query detail Opening a query shows the following tabs. | Tab {.nowrap} | Contents | | --- | --- | | **Overview** | Metadata such as description and tags | | **Columns** | Column information | | **SQL** | The saved SQL | | **Preview** | A preview of the execution results | | **References** | Reference relationships | | **Query jobs** | Related query jobs | You can also edit and manage the query itself from the [Query](../saved-query/overview) screen. ## Popularity and references {#popularity-and-references} The catalog lets you check how much a resource is used (**popularity**) and where it's referenced from (**references**). ### Popularity {#popularity} Shown in the **Popularity** column of the list (for both tables and queries). * Popularity is based on the number of **query jobs** that reference the resource. * The tooltip shows the number of referencing jobs, and **View job list** takes you to the **Query jobs** tab for details. Popularity is shown as a relative score. If there are no jobs, popularity is empty (or 0). ### References {#references} The **References** tab on the detail screen shows the following. * **Referencing notebooks**: Notebooks that reference this table (or query). * **Referencing queries**: Saved queries that reference this table (or query). If there are no references, it shows **Not referenced**. ### Query jobs {#query-jobs} The **Query jobs** tab on the detail screen shows the history of query jobs that referenced this resource. You can also use it as the list of jobs behind the popularity score. ## Filtering and search {#search-filters} In addition to keywords, the search field above the list lets you filter using the following keys, chosen from suggestions. You can combine multiple keys separated by spaces. Suggestions appear as you type a key. ### Table | Key {.nowrap} | Description | | --- | --- | | `connection:` | Connection | | `database:` | Database (project, for BigQuery) | | `schema:` | Schema (dataset, for BigQuery) | | `type:` | Table type | | `tag:` | Table tag | | `updatedBy:` | Updated by | | `is:` | `starred` (starred items only) | | `sortBy:` | Sort order. Suggestions are `Popularity` / `Rows` | ### Query | Key {.nowrap} | Description | | --- | --- | | `connection:` | Connection | | `tag:` | Query tag | | `createdBy:` | Created by | | `updatedBy:` | Updated by | | `is:` | `starred` (starred items only) | | `sortBy:` | Sort order. Suggestions are `Popularity` / `Updated` | Applied conditions appear as tags near the search field (for example, `is:starred`). ## Starred Use the star icon in the list or detail screen to star or unstar a table or query. You can filter starred resources using **Common filters** > **Starred** in the left sidebar, or with `is:starred` in search. ## Creating notebooks/queries {#create-from-catalog} The **Actions** menu on the list lets you create resources starting from the selected item. * **Create notebook**: Creates a notebook from a table or query. * **Create query**: Creates a saved query from a table (table list only). **Create notebook** is disabled if you've reached your notebook limit. --- --- url: 'https://docs.codatum.com/features/catalog/metadata-sync.md' description: Syncing table and column metadata from connections into the catalog --- # Table metadata sync Syncing table metadata saves information about tables and columns to Codatum, where it becomes available in the [catalog](./overview) and elsewhere. Automatic sync runs for connections where roughly **7 days** have passed since the last sync check. If you need an immediate update, sync manually. SQL execution results are returned regardless of the table metadata sync status. If results don't seem up to date, you might be seeing a cached result (see the cache section of [SQL block](../notebook/doc-page/sql-block#cache)). ## Table identity {#table-identity} Synced tables are managed by the underlying object on the warehouse, not by connection. Within a workspace, the same underlying object is treated as a single table. The elements that determine identity vary by warehouse. | Warehouse {.nowrap} | Matching elements | | --- | --- | | BigQuery | Project / dataset / table | | Snowflake | Account / database / schema / table | | Databricks | Host and SQL warehouse / catalog / schema / table | | Redshift | Account, region, cluster (or namespace) / database / schema / table | For example, in BigQuery, tables are the same if the project, dataset, and table match. Even from different connections, they appear as a single entry in the catalog. When multiple connections sync the same table, Codatum handles it as follows. * The catalog shows it as a single table. You can see the related connections on the table detail. * Descriptions, tags, and other annotations are shared across the same table. * You can view it if you have read permission on any related connection, and edit it if you have run permission on any related connection. See [Catalog permissions](../../permissions/resources/catalog) for details. ## Information collected Codatum imports the following from your warehouse (some fields might be empty depending on the warehouse or permissions). * Table structure: database name, schema name (dataset name for BigQuery), table name, table type * Table description * Row count * Table size (bytes) * Table creation and update timestamps * Column name, data type, column description, and nullability The **Other** tab on the table detail shows whatever additional items are available, such as definition, data location, view query, and partition information. ### Differences by warehouse * **Redshift**: Column descriptions aren't imported during sync. Table update timestamps aren't imported either. * **BigQuery** and others: Warehouse-specific information such as partitioning and clustering might appear in **Other**. ## When sync runs * **Automatic sync**: Runs for connections where roughly 7 days have passed since the last sync check. * **Manual sync**: Open the target connection under [global nav](../../guide/screen-layout) > **Workspace settings** > **Data management** > **Connections**, then select **Resync Immediately** in **Table sync settings**. * **When saving sync targets**: Selecting **Save and sync** while editing **Sync targets** triggers a sync after the targets are updated. ## Sync targets {#sync-target} Choose the databases/schemas (datasets) to sync from **Table sync settings** on the connection detail. You can also set **Sync targets** when creating the connection. * **Auto add datasets** (BigQuery) / **Auto add schemas** (other warehouses): Automatically adds newly created databases/schemas, or ones you've newly been granted access to, to the sync targets (on by default). This doesn't apply once the number of schemas/datasets in a database exceeds a certain threshold. * You can select up to 200 schemas/datasets. The demo connection's sync targets are fixed and can't be edited. See [Demo connection](../connection/overview#demo-connection) for details. ## Sync status The on-screen labels map to the following status codes. | Label {.nowrap} | Code | | --- | --- | | QUEUED | `PENDING` | | PROCESSING | `RUNNING` | | SUCCESS | `SUCCESS` | | WARNING | `WARNING` | | FAILED | `ERROR` | You can check the sync history from **Sync history** in **Table sync settings** on the connection detail. ## Where it's used Synced table metadata is used in the following, among others. * [Catalog](./overview) * Autocomplete in SQL blocks * Column information in table overviews across various features ## Permissions * Viewing synced table metadata is limited to users with read permission on a connection associated with the table. * For how Codatum handles tables synced by multiple connections, see [Table identity](#table-identity). * **Resync Immediately** and changing sync targets require run permission on the target connection. See [Connection permissions](../../permissions/resources/connection) for details. ## Limits * Number of synced tables: Depends on your contract (check under [global nav](../../guide/screen-layout) > **Workspace settings** > **Usage**). * Number of schemas (datasets) you can select as sync targets: Up to 200. * Number of tables that can be synced per schema: Up to 1,000. See also [Limits](../../reference/limits#fixed-limits) (fixed limits) and [Limits that depend on your contract](../../reference/limits#plan-limits). ## If a table can't be found 1. Check the sync status for errors. 2. Confirm the database and table are selected as a [sync target](#sync-target). 3. Confirm the connection's credentials have permission to read the table. 4. If it's still not found, run **Resync Immediately**. --- --- url: 'https://docs.codatum.com/features/catalog/annotation.md' description: Adding descriptions and tags to tables and columns --- # Annotation The catalog lets you add a **description** and **tags** to tables and columns. This combination is called an annotation. Bulk updates from the CLI are also supported; see the [Codatum CLI documentation](https://cli-docs.codatum.com) for details. For tag definitions and types, see [Tag](../../workspace/data-management/tag#tag-types). ## Targets | Target {.nowrap} | What you can do | Example UI location | | --- | --- | --- | | Table | Add a description and tags | **Overview** on the table detail, or the description/tag columns in the list | | Column | Add a description and tags | **Columns** on the table detail | ### Adding tags to tables/columns Add these from the table list or detail in the [catalog](./overview). * Table: **Add tag** in **Overview**, or **Add tag** in the tag column of the list. * Column: **Add tag** on the **Columns** tab. You can only add a **table tag** to a table, and a **column tag** to a column. If a description was synced from the warehouse, you view and edit it in the same **Description** field in the catalog. See [Table metadata sync](./metadata-sync) for how syncing works. ## Difference from saved queries The description and tags on a saved query are managed as query-side metadata, separate from table annotations. You can edit them from the catalog's **Queries** list/detail, or from the [Query](../saved-query/overview) screen. ## Permissions To edit a description or tags on a table or column, you need run permission on at least one of the related connections. Viewing depends on read permission on the related connections. Creating and editing tag definitions is controlled by workspace role (see [Tag](../../workspace/data-management/tag#tag-definition)). For details, see [Catalog](../../permissions/resources/catalog). ## Search Descriptions and tags are included in keyword search. For search across resource types, see [Quick search](../quick-search/overview). --- --- url: 'https://docs.codatum.com/features/saved-query/overview.md' description: SQL you save and reuse per connection --- # Query (Beta) Query (sometimes called a **saved query**) lets you save SQL to reuse per [connection](../connection/overview). You can reference the same SQL from multiple notebooks, or run it directly from the query screen. Open it from [global nav](../../guide/screen-layout) > **Queries**. There's no dedicated resource role. What you can do depends on the permissions of the connection it belongs to. See [Query permissions](../../permissions/resources/query) for details. ::: info This feature is in **beta**. The specification might change without notice. ::: ## Key features * Saving and running SQL: Edit and save SQL on the query screen, then run it with **Run**. * Organizing with folders: Organize queries under each connection. * Notebook integration: **Save SQL** from a SQL block, and reference a saved query with `/` (see [SQL block](../notebook/doc-page/sql-block)). * **Queries** tab in the [catalog](../catalog/overview): View and edit metadata (description, tags, columns, references, popularity, and so on). * [Workflow](../workflow/overview): Run a saved query on a schedule. * [Tags](../../workspace/data-management/tag): Add query tags. Definitions are managed in workspace settings. ## Creating a query ### From the query screen 1. Open [global nav](../../guide/screen-layout) > **Queries**. 2. Select **New query** (opens a draft where you can choose a connection). 3. Edit the SQL, then select **Save** and specify a name, connection, and folder to save it for real. Selecting **New query** from a connection or folder in the [left sidebar](../../guide/screen-layout) creates an empty query directly at that location. You can also create and move folders from the left sidebar. ### From a notebook 1. Select **Save SQL** from the menu at the top right of a SQL block. 2. Specify a name, connection, and folder, then save. Saving behaves as follows. * References to other SQL blocks or saved queries are saved as expanded SQL strings. * Parameters are saved with their current values substituted in. * The description automatically includes a link back to the source notebook (`Source notebook: ...`). * If a recent execution result exists, column information can also be saved. ## Editing, running, and managing | Action {.nowrap} | Description | | --- | --- | | **Save** / **Save as...** | Updates the SQL, name, and so on. You can also save as a copy | | **Run** | Runs the SQL using the credentials of the connection it belongs to | | Star | Add or remove from the **Starred** tab in the list, and from quick search | | Description/tags | Edit from the query detail, or from the [catalog](../catalog/overview) | | Columns | You can add descriptions and tags (managed based on the columns from execution results) | | **Create notebook** | Creates a new notebook that includes this query | | Move/delete | Available from the left sidebar or the detail menu. You can only move within the same connection | | **History** | View past versions | Once saved, you can't change the connection a query belongs to. To use a different connection, recreate it as a new query with **Save as...** or similar. ## Integration with notebooks * **Referencing**: In a SQL block, type `/` and insert from **Saved query**. This embeds the SQL as of the time you inserted it, and that embedded SQL is what runs. If the source query changes, the reference chip shows **Diff found**, and you can apply it with **Update embedded query**. * **Saving**: **Save SQL** turns references and parameters into fixed, expanded SQL. See [SQL block](../notebook/doc-page/sql-block) for the notebook side of this. ## Constraints * You can't change which connection a query belongs to (after saving). * You can only move a query or folder within the same connection. * Folders can be nested up to 5 levels deep ([Limits](../../reference/limits#fixed-limits)). * Deleting a folder also deletes the queries in it. * The maximum number of queries depends on your contract ([Limits](../../reference/limits#plan-limits); check under [global nav](../../guide/screen-layout) > **Workspace settings** > **Usage**). * [Deleting a connection](../connection/overview) also deletes its related saved queries. ## Permissions See [Query permissions](../../permissions/resources/query) for the conditions for each action. Viewing requires a connection's read-level permission; editing, running, and folder operations require its run permission. --- --- url: 'https://docs.codatum.com/features/notebook/overview.md' description: 'Real-time collaborative editing, page types, and key features of notebooks' --- # Notebook A notebook is your workspace for data analysis. You can bring SQL, charts, and text together in a single document, with real-time collaborative editing. Access it from [the global nav](../../guide/screen-layout) > **Notebooks**. A notebook consists of multiple pages. Use a [doc page](./doc-page/overview) for analysis work, and a [grid page](./grid-page/overview) for dashboard layouts. You can also use **section dividers** in the page list. See [notebook permissions](../../permissions/resources/notebook) for details on permissions. With real-time collaborative editing, the content of a notebook (SQL, charts, text, and so on) is synced between users who have the same page open. See [Parameter](./parameter/overview) for how parameters and run results are synced. To keep parameter operations independent per user, use [Version](./version) or [Report](./sharing/report/overview). ## Key features * [Folder](./folder) / [Teamspace](../../workspace/administration/teamspace): placement and access scope * [Doc page](./doc-page/overview): a flow-based block editor (insert with `/`) * [Grid page](./grid-page/overview): tile layout for charts and more. [Cross filter](./grid-page/cross-filter) * [SQL block](./doc-page/sql-block): SQL editing, execution, result display, chart creation, and [caching](./doc-page/sql-block#cache) * [Parameter](./parameter/overview): embedding in SQL and input forms * [Chart](./chart/overview): visualization based on dimensions and metrics * [Explorer](./explorer): explore data with a GUI and create charts or SQL blocks * [Comment](./comment): comments and mentions in the notebook body * [Version](./version): save, restore, and compare analysis states * [Lock](#lock): prevent accidental edits (**Unlocked** / **Query only** / **Locked**) * [Notebook theme](../../workspace/administration/theme): customize chart colors and fonts * [Export and import](./export) * [Sharing](./sharing/overview): permissions / report / public link / signed embed * [FAQ](./faq) ## Creating and managing notebooks {#create-manage} ### Creating You can create a notebook in either of the following ways. 1. Open [the global nav](../../guide/screen-layout) > **Notebooks**, then select **Create notebook** or **Create from template**. 2. In the folder tree in [the left sidebar](../../guide/screen-layout), open **Add notebook or folder** and select **New notebook**. You can also use a template or import a file from the same menu. On the top screen, you can find notebooks using the **Recently viewed**, **Created by me**, **Starred**, and **Active** tabs. ### Creating from a template {#templates} **Create from template** lets you create a new notebook from one of the available notebook templates. Templates are listed by category. After reviewing a template, select **Create from template** / **Create** to create the notebook. ### Adding pages {#add-page} In the page list at the top of [the left sidebar](../../guide/screen-layout) inside a notebook, select **Add** > **Page** to add a page. | Type {.nowrap} | Description | | --- | --- | | [**Doc page**](./doc-page/overview) | A flow-based document format for placing SQL, charts, text, and more. | | [**Grid page**](./grid-page/overview) | Arranges charts defined on doc pages as a dashboard. | | **Section divider** | Used to divide the page list. It has no body content. | You can **Rename**, **Duplicate page**, or **Delete** a page from that page's menu. ### Notebook operations From the menu in [the header](../../guide/screen-layout) inside a notebook, you can perform the following operations. * [**Share**](./sharing/overview): grant permissions, and publish reports, public links, or signed embeds * [**Export**](./export) / **Import pages** * [**Notebook theme**](../../workspace/administration/theme) * [**Version**](./version) * [**Lock notebook**](#lock) * [**Show dependencies**](#dependencies) **About this notebook** in the header shows details such as the created time and size. From the list view, you can move, delete, and star notebooks. ## Lock {#lock} Lock is a feature that prevents accidental edits to a notebook. Switch the state from the **⋯** (horizontal three-dot icon) > **Lock notebook** menu in [the header](../../guide/screen-layout) inside a notebook. Changing this setting requires edit permission on the notebook. You can't change the lock state of a notebook you can only access through sharing. | State {.nowrap} | Description | | --- | --- | | **Unlocked** | Everything can be edited. | | **Query only** | Only parameter changes and SQL execution are allowed. | | **Locked** | Only [comments](./comment) are allowed. | When the state is **Query only** or **Locked**, enabling **Temporarily unlock** lets you remove the lock for yourself only. The lock is automatically restored when you close or reload the notebook. ## Dependencies {#dependencies} Open **Show dependencies** to see a diagram of the SQL blocks and parameters in the notebook, along with their reference relationships. You can also open the same diagram from the menu of a SQL block, a grid component, or a parameter. Use this to trace references between SQL blocks (SQL chains) and parameter reference chains. See [SQL block](./doc-page/sql-block#references) for details on references between SQL blocks. ## Constraints * You can't edit a notebook once its size exceeds 10MB (see [Limits](../../reference/limits#fixed-limits)). * The maximum number of notebooks depends on your contract (see [Limits](../../reference/limits#plan-limits); you can check this from the global nav > **Workspace settings** > **Usage**). ## Permissions See [Notebook](../../permissions/resources/notebook) for the conditions for each operation. Whether SQL can be run is determined by permissions on the target [connection](../../permissions/resources/connection), not by notebook permissions. --- --- url: 'https://docs.codatum.com/features/notebook/doc-page/overview.md' description: A flow-based notebook page type --- # Doc page Doc page is one of the notebook page types. It's a flow-based block editor, used for analysis by arranging SQL blocks, charts, text, and more vertically. You can use the following blocks within a page. While editing, type `/` to choose from a list of available blocks. See [Grid page](../grid-page/overview) for dashboard-style tile layouts. Charts and SQL run results placed on a grid page are first defined on a doc page. ## Key features * A flow-based block editor (arrange SQL blocks, charts, text, and more) * [SQL block](./sql-block): SQL editing, execution, result display, and chart creation * [Parameter](../parameter/overview): an input form at the top of the page and embedding in SQL * [Chart](../chart/overview): visualizing SQL block run results * [Explorer](../explorer): exploring data through a GUI * Full-text search ## Available blocks {#blocks} The blocks available on a doc page are grouped as follows. You can select one while editing by typing `/`, or from **Add** in a block's hover menu. ### Data analysis | Block {.nowrap} | Description | | --- | --- | | **[SQL block](./sql-block)** | Used for SQL editing and execution, showing run results, column statistics, and chart creation. | | **Table preview** | Shows sample rows from a table on a connection within the page. You can also launch Explorer from it. | | **Block chart** | Visualizes the run result of a SQL block on the same page as a [chart](../chart/overview). In addition to placing it as a vertical block, you can convert it to an inline chart and place it within a list or text table. | | **Scalar value reference** | Embeds the value of a specified column from the first row of a SQL block's run result on the same page, directly within text. | ### Code | Block {.nowrap} | Description | | --- | --- | | **Code block** | Displays code with syntax highlighting. | | **Diagram block** | Renders a diagram in [Mermaid](https://mermaid.js.org/) format. | | **Block equation** | Displays a formula in [KaTeX](https://katex.org/) format. Inline formulas within text are also supported. | ### Text | Block {.nowrap} | Description | | --- | --- | | **Heading 1** / **Heading 2** / **Heading 3** | Headings within the page (3 levels). | | **Bulleted list** | A list with bullet markers. | | **Ordered list** | A numbered list. | | **Task list** | A list that can track completion state. | | **Togglable list** | A list you can expand and collapse. | | **Divider** | A horizontal line. | | **Callout block** | Emphasizes content by type (info, success, warning, danger). You can also specify an emoji icon. | | **Quote block** | A quote. It can only contain paragraphs or lists. | | **Text table** | A table whose cells can contain paragraphs or lists. Supports cell merging and column width settings. | ### Layout | Block {.nowrap} | Description | | --- | --- | | **2 columns** / **3 columns** / **4 columns** / **5 columns** | A multi-column layout. Each column can contain paragraphs, lists, and charts (SQL blocks and similar can't be placed). | ### Media | Block {.nowrap} | Description | | --- | --- | | **Image** / **Video** | Place a file by selecting or pasting it into the page. | | **Link notebook** | A link to another notebook. You can also add it by pasting a URL. | | **Embed block** | Embeds external content from a supported URL, such as YouTube. You can also add it by pasting a URL. | | **Emoji** | Select and insert an emoji from a picker. | --- --- url: 'https://docs.codatum.com/features/notebook/doc-page/sql-block.md' description: The unit for editing and running SQL within a notebook --- # SQL block A SQL block on a [doc page](./overview) lets you edit and run SQL, view run results, view column statistics, and create charts. Add one from a doc page by typing `/` and selecting **SQL block**. ## Key features * Editing and running SQL * Autocomplete, highlighting, and formatting * Table search and reference insertion via `/` * [References to other SQL blocks](#sql-block-ref) (SQL chains) and [expanding/overriding parameters](#param-in-sql-ref) * [Adding a chart](#add-chart) * [Adding column stats](#column-stats) * [Code snippets](#code-snippet) * Referencing saved queries, and creating saved queries with **Save SQL** (see [Query](../../saved-query/overview)) * Launching [Explorer](../explorer) from a SQL run result * [Display modes](#display-mode) * [Cache](#cache) ## References {#references} In the SQL editor, type `/` to reference the following. | Reference target {.nowrap} | Insert example | Description | | --- | --- | --- | | [Another SQL block](#sql-block-ref) | `/sql/` | Expands the referenced SQL as a subquery. | | Table | `/table/` | Lets you select a table from the catalog. | | Parameter | `/param/` | Embeds a [parameter](../parameter/overview)'s value. | | Saved query | `/query/` | Embeds the SQL at the time of insertion. When the source is updated, select **Update embedded query** to apply the change. See [Query](../../saved-query/overview) for details. | You can also see reference relationships in the notebook's [dependency diagram](../overview#dependencies). Open **Show dependencies** from a SQL block's menu. ### Referencing SQL blocks {#sql-block-ref} When you reference another SQL block, the referenced SQL is expanded as a subquery at run time. This lets you factor out and reuse common extraction logic, or build up a query while checking intermediate results block by block. * You can reference SQL blocks on the same page, as well as SQL blocks on **other doc pages** within the same notebook. * References to other pages are shown as `Page name.SQL block name`. * Circular references result in an error. #### Inserting 1. In the SQL editor, type `/sql/`, or choose **Reference another SQL block's SQL** from the `/` suggestions. 2. Select the SQL block you want to reference. #### Expansion settings Hovering over a reference chip shows a popup where **Settings** lets you change the following. | Item {.nowrap} | Description | | --- | --- | | **Don't wrap in parentheses** | Off by default. When off, the expanded result is wrapped in `(` `)`. Turning it on omits the wrapping. | | **Add alias at the end** | Only selectable when **Don't wrap in parentheses** is off. Appends `AS` and the SQL block name at the end of the expanded result. | ### Expanding and overriding parameters {#param-in-sql-ref} If the referenced SQL block contains a parameter reference, the value used for expansion is as follows. | Parameter used by the reference target | Value used for expansion | | --- | --- | | [Notebook-wide](../parameter/overview#scope) | The value held by the **referencing source** (the page containing this SQL block). | | [Page-specific](../parameter/overview#scope) | If the referencing page has no definition with the same name, the value from the **reference target**'s page. | If you want to decouple the parameter dependency on the referencing page, use **Override internal parameter references** in the reference chip's popup. | Method {.nowrap} | Description | | --- | --- | | **Override with another parameter** | Replaces the value with another parameter of the same type. | | **Override with a fixed value** | Specifies a fixed value. | | **Don't override** | Expands according to the rules above. | You can override the same way when referencing from a grid page's SQL run result or chart. See [Overriding parameters](../parameter/overview#override) for details. ## Adding a chart {#add-chart} Once SQL runs successfully, select **Chart** in the run result header to open the chart wizard. Configure dimensions, metrics, and so on to add a chart directly below the run result. * See [Chart](../chart/overview) for details on chart types and settings. * You can also add a chart from [Explorer](../explorer). * An added chart can also be placed on a [grid page](../grid-page/overview) using **Add to grid page**. * You can also insert a **Block chart** via `/` to reference the run result of a SQL block on the same page (see [Doc page](./overview#blocks)). ## Adding column stats {#column-stats} Select **Column stats** in the run result header to add the distribution and summary statistics of a result column. Selecting a target column issues a separate SQL query and adds a column stats block. The items shown vary depending on the data type. | Item {.nowrap} | Description | | --- | --- | | **Data type** | The column's data type. | | **Number of NULL values** | The count and percentage of NULLs. | | **Unique count\*** | The number of unique values. | | **Max** / **Min** / **Average** | Shown for numeric, time, and similar types. | | **Percentiles\*** | The 25th, 50th, and 75th percentiles. | | **Character length\*** | The distribution of string lengths. | | **Frequency\*** | The most frequently occurring values. | | **Histogram\*** | The distribution for numeric, time, and similar types. | Values marked with `*` are calculated using an approximation function. Available connections are [BigQuery](../../connection/warehouses/bigquery), [Snowflake](../../connection/warehouses/snowflake), and [Databricks](../../connection/warehouses/databricks). Not available for [Redshift](../../connection/warehouses/redshift). If the SQL content or parameters change, you need to re-run the stats. ## Display mode {#display-mode} The icon at the top left of a SQL block lets you switch the display mode. This switch isn't synced to other users. You can change the default setting from the SQL block menu **⋯** (horizontal three-dot icon) > **Default display**. | Mode {.nowrap} | Description | | --- | --- | | **Show all** | Shows SQL, the run result, and the chart. | | **Show result only** | Shows the run result and the chart. | | **Hide all** | Hides SQL, the run result, and the chart. | ## Save SQL Use **Save SQL** in the SQL block's top-right menu to register the block's content as a saved query. * References to other SQL blocks or saved queries are saved fully expanded. * Parameters are saved with their value at that point substituted in. Parameter embedding and references to other queries aren't available on the saved query side. ## Code snippets {#code-snippet} Use **Manage code snippets** in the SQL editor to create and edit snippets for autocomplete. Code snippet autocomplete is enabled by default. You can disable it by turning off **Enable code snippet autocomplete** in [SQL editor preferences](../../../account/settings/editor). | Item | Description | | --- | --- | | **Personal snippet** / **Shared snippet** | Choose whether it's personal (per user) or shared across the workspace. | | **Autocomplete key** | Typing this key lets you call up the snippet from autocomplete suggestions. | | **Code snippet to insert** | The text inserted when the suggestion is selected. You can specify the cursor position after insertion with `$$`. | | **Display name** / description | Optional. | ## Cache {#cache} A SQL block's run result is cached for display purposes. This reuses the past successful result of the same SQL; the job itself is retained for 24 hours by default. * Up to 1,000 rows of run result are retained for display. * When editing a notebook, running a new job is skipped by default if the cache is within 24 hours, and the cache is used instead. * To run without using the cache, use a SQL block's **Run with latest data**, or the notebook's **Run all with latest data**. The handling differs by access path, as follows. | Path {.nowrap} | Display cache | Overriding the reuse period | | --- | --- | --- | | Editing a notebook | 24 hours by default. Can be bypassed with **Run with latest data** / **Run all with latest data**. | None. | | Viewing a report | Same as above. | [Report settings](../sharing/report/overview#report-settings)' **Cache duration** (24 hours by default; 0 disables it; maximum 24 hours, in 10-minute increments). | | Signed embed | Same as above. | `cache_max_age` at token issuance (86400 seconds by default and at maximum; 0 disables it). See [Signed embed](../sharing/signed-embed/overview) for details. | Warehouse-side caching (such as the DWH's native cache for identical SQL) can't be controlled from the connection settings. ## Constraints {#constraints} Column suggestions and similar are available only when you use a table reference or a reference to another SQL block. They aren't suggested for string table IDs or saved query references. --- --- url: 'https://docs.codatum.com/features/notebook/grid-page/overview.md' description: A page for arranging charts and other components as tiles --- # Grid page Grid page is one of the notebook page types. It arranges charts and SQL run results defined on a [doc page](../doc-page/overview) as a tile-based dashboard. You can place, reorder, resize, and drag and drop components. Analysis (creating SQL and charts) is done on the doc page, and the grid page arranges them by reference. Even when you create a new chart from the grid page's right sidebar, the chart itself is created on the doc page side. ## Key features * Tile-based layout (drag and drop, resizing, mobile layout) * Placing components from **Components** in the right sidebar (built-in elements, charts, query results) * [Grid settings](#grid-settings) (columns, row height, edit guide) * Displaying [parameters](../parameter/overview), and [overriding parameters](../parameter/overview#override) per placed component * [Explorer](../explorer) * [Cross filter](./cross-filter) ## Available components {#components} The components available on a grid page are grouped as follows. Place them from **Components** in [the right sidebar](../../../guide/screen-layout). ### Built-in Elements specific to grid pages. Not shared with doc pages. | Component {.nowrap} | Description | | --- | --- | | **Heading** | A heading (**Heading 1** / **Heading 2** / **Heading 3**). You can also add a description. | | **Text** | Places supplementary text. | | **Image** | Upload and place an image. You can adjust its size and position. | | **Spacer** | Blank space between components. You can also configure whether it's shown in the mobile layout. | ### From doc pages Places SQL blocks and charts defined on a doc page by reference. In the right sidebar, candidates under the **Chart** section are listed by doc page name, then SQL block name. | Component {.nowrap} | Description | | --- | --- | | **Chart** | Places a [chart](../chart/overview) created on a doc page. You can also create a new chart from an existing SQL block using **New chart** in the right sidebar. | | **Query result** | Places the run result table of a doc page's [SQL block](../doc-page/sql-block). There's one candidate per SQL block. | If there are no SQL blocks or charts on the doc page side, no candidates are shown. Candidates that are already placed show **In use**. For charts and SQL run results, you can configure [parameter overrides](../parameter/overview#override) and [cross filter](./cross-filter) per component. ## Grid settings {#grid-settings} From **Grid settings** in the header, you can configure the grid granularity and the background guide shown while editing. | Item {.nowrap} | Description | | --- | --- | | **Columns** | The number of columns the page is divided into horizontally. An integer from 1 to 60. The default is 12. | | **Row height (px)** | The height of one vertical grid unit. An integer from 10 to 120. The default is 60. | | **Edit guide** | The background guide shown while editing. Choose from **None** / **Dots** / **Grid lines**. The default is **Grid lines**. | * Columns and row height take effect when you change the values and select **Apply**. They're saved as page settings and apply to all users viewing the page. * The edit guide takes effect as soon as you select it. It applies only to your own screen and doesn't affect other users. * When you change the number of columns, placed components are converted to the new grid while keeping their width ratios as much as possible. Components that no longer fit side by side after reducing the number of columns are automatically stacked vertically. * For the value ranges, see [Limits](../../../reference/limits). ## Syncing chart settings {#chart-sync} * Settings for the chart itself, such as axes and type, are synced with the doc page side. Even if the same chart is placed on multiple grids, its settings are shared. * Display settings on the grid, such as header display and component titles, aren't synced. * Parameter overrides and cross filter settings are also specific to each component on the grid. * Chart settings aren't shared with other users until explicitly saved. --- --- url: 'https://docs.codatum.com/features/notebook/grid-page/cross-filter.md' description: Synchronize filtering of charts and tables on a grid page using keys --- # Cross filter Cross filter syncs the filtering state, such as legend, axis, and frame selections, between [charts](../chart/overview) and [query results](./overview#components) placed on a [grid page](./overview). Components that share the same key are linked together. Filtering is applied to data already loaded on the frontend. No additional SQL job runs when a filter changes. Cross filter settings are specific to each component on the grid, and [aren't synced with the chart settings on the doc page side](./overview#chart-sync). ## Configuring A chart or query result must already be placed on the grid page. 1. Hover over the target component and open **Cross filter** from the top-right menu. 2. If it's not yet configured, select **Edit**. 3. Enter a key for each item you want to link (components that share the same key are linked together). 4. Select **Apply**. To remove the setting, select **Clear filter** from the same menu. The items shown vary depending on the chart type and its settings. For example, a chart that doesn't use the [frame feature](../chart/common-settings/frame#frame-feature) doesn't show **Frame key**. ## Settings {#settings} | Item {.nowrap} | Description | | --- | --- | | **Legend key** | Syncs whether the legend is shown or hidden. Legend names must match. | | **X-axis key** | Syncs the X-axis display range. The axis type and content must match. | | **Y-axis key** | Syncs the Y-axis display range. The axis type and content must match. | | **Frame key** | Syncs the displayed [frame](../chart/common-settings/frame#frame-feature). The frame value must match. | | **Data filter** | Filters the table's displayed data in sync with the chart-side filtering. Add a condition using a combination of **column** and **key**. | **Data filter** requires you to specify the following two items. | Item {.nowrap} | Description | | --- | --- | | **Column** | The target column to filter by value. | | **Key** | The key configured on the linked chart's legend, axis, or frame. | ## Syncing the same field type {#same-field-sync} Setting the same key on the same type of item syncs the same operation. ### Legend * Targets: [XY Chart](../chart/xy-chart), [Radial Chart](../chart/radial-chart), [XYZ Chart](../chart/xyz-chart) (excluding heatmap), [Funnel Chart](../chart/funnel-chart). * Syncs legend selection, deselection, and hover highlighting. * Links series with matching legend names. ### X axis / Y axis * **X-axis key** targets: [XY Chart](../chart/xy-chart), [XYZ Chart](../chart/xyz-chart), [Waterfall Chart](../chart/waterfall-chart). * **Y-axis key** targets: [XYZ Chart](../chart/xyz-chart). * Syncs axis range selection (zoom). * The axis type (category, time, numeric, and so on) must match. * For a category axis, filtering is based on the index range according to the data's display order. ### Frame * Targets: [XY Chart](../chart/xy-chart), [Radial Chart](../chart/radial-chart), [XYZ Chart](../chart/xyz-chart), [Funnel Chart](../chart/funnel-chart), [Waterfall Chart](../chart/waterfall-chart), [Graph Chart](../chart/graph-chart), [Hierarchy Chart](../chart/hierarchy-chart), [Word Cloud](../chart/word-cloud). * Only effective when the [frame layout](../chart/common-settings/frame#frame-feature) is timeline. * The frame value must match. ### Data filter * Targets: [Query result](./overview#components), [Table Chart](../chart/table-chart). * Even between tables sharing the same **key**, filtering syncs based on the value of the specified **column**. ## Syncing across different fields {#cross-field-sync} Setting the same key on different types of items links them across fields. | Link | Behavior | | --- | --- | | **X-axis key** ↔ **Y-axis key** | Syncs the display range of the X axis and Y axis. | | **Legend key** ↔ **X-axis key** / **Y-axis key** | Syncs legend and axis filtering. Only links when the axis is a [category axis](../chart/xy-chart#axis-category). If multiple legend items are selected, filters by the range from the minimum to maximum of the corresponding axis indices. | | **Legend key** ↔ **Frame key** | Syncs legend and frame. Only effective for a timeline layout, and only links when a single legend item is selected. | | **Legend key** → **Data filter** | Reflects legend filtering onto the table. The legend name must match the **column** value. There's no sync in the reverse direction from the table. | | **X-axis key** / **Y-axis key** → **Data filter** | Reflects the axis display range onto the table. The axis value must match the **column** value. There's no sync in the reverse direction from the table. | | **Frame key** → **Data filter** | Reflects the frame value onto the table. The frame value must match the **column** value. There's no sync in the reverse direction from the table. | ## Constraints {#limitations} * Only data already loaded on the frontend is targeted. Because SQL isn't re-run, for example, narrowing an axis's period can't be reflected in a radial chart's aggregated result. * Filtering can't be reflected from a table (query result or table chart) to other charts. * Because linking from legend to axis works via range selection, adjacent categories between the selected legend items are also included. * Linking between category axes (string axes) depends on display order. If the display order differs, linking won't work correctly. * When the frame layout is grid, syncing axes and frames isn't available. --- --- url: 'https://docs.codatum.com/features/notebook/parameter/overview.md' description: Parameter scope and embedding values in SQL --- # Parameter Referencing a parameter from a SQL block lets you generate SQL dynamically based on the parameter's value. Once you define a parameter, an input form appears at the top of the [doc page](../doc-page/overview) or [grid page](../grid-page/overview). A notebook's parameter values and run results are synced between users currently viewing it. To keep them independent per user, use [Version](../version) or [Report](../sharing/report/overview). ## Key features * Scope: [notebook-wide / page-specific](#scope) * [Types and data types](./types) * [Usage patterns in SQL](./sql-patterns) * [Escaping and dynamic references](./escape-and-dynamic-reference) * [Relative dates](./relative-date) * [Generating dynamic options](./dynamic-options) * [Specifying values from a URL](./url) ## Creating and managing {#create-manage} 1. Open **Parameter** at the top of [the main area](../../../guide/screen-layout). 2. Select **Add parameter**, then choose a scope (**Notebook-wide** / **Page-specific**) and a type. 3. In a [SQL block](../doc-page/sql-block), type `/param/` and select the parameter from the suggestions. Once selected, the parameter reference is embedded in the SQL. It's displayed using the parameter's label. For example, if a string parameter labeled `param1` has `val1` entered, the following SQL expands to `'val1'` at run time. ```sql -- Display in the SQL block SELECT {{param1}} -- Generated SQL SELECT 'val1' ``` :::: tip ::: v-pre The `{{param1}}` above is a notation used for explanation. On screen, it's shown as a labeled reference chip. ::: :::: For each parameter, you can do the following. | Operation {.nowrap} | Description | | --- | --- | | **Settings** | Edits the input form settings for that type (see [Types and data types](./types)). | | **Default value** | Sets the value applied when resetting. For date types, you can also choose a [relative date](./relative-date). | | **Reset to default value** | Resets that parameter's current value to its default value. | | **Delete** | Deletes the parameter definition. A parameter currently referenced from a SQL block or elsewhere can't be deleted. | In the parameter form, you can switch the display between **In use** and **Show all**. | Display {.nowrap} | Description | | --- | --- | | **In use** | Shows only parameters referenced from the SQL and so on of the selected page. | | **Show all** | Shows all defined parameters, regardless of whether they're referenced. | The **Reset** button resets all displayed parameters to their default values at once. ## Parameter scope {#scope} A parameter has one of two scopes. Regardless of scope, **the value is held per page**. | Scope {.nowrap} | Description | | --- | --- | | **Notebook-wide** | The parameter definition is shared across all pages in the notebook. The value is held on each page. | | **Page-specific** | The parameter definition is only valid within the selected page. The value is also held only on the selected page. | Choose **Notebook-wide** for use in a SQL block referenced from multiple pages, and **Page-specific** for use only within that page. For example, when referencing a chart created on a doc page from a grid page, the SQL block that's the chart's data source should use a notebook-wide parameter. ## Resolving values and default values {#value-resolution} What's embedded in SQL is the **parameter value** held on each page. * The **default value** is written into the parameter's value when you run **Reset** (or the individual **Reset to default value**). * A parameter with no value set (an empty input form) expands using the [zero value](./types#types) for its type. * Because the zero value is a value valid for SQL of each type, SQL usually doesn't error out even when the value is unset. See [Usage patterns in SQL](./sql-patterns) for how to write an optional filter when the value is unset. If you set a relative date as a date's default value, the date at that point in time is written into the current value each time you reset. See [Relative dates](./relative-date) for when this is applied. ## Overriding parameters {#override} When referencing a SQL block (chaining SQL blocks), you might want to decouple the parameter dependency inside the referenced SQL. For example, in cases like the following. * Chaining SQL across pages, where each page should reference its own specific parameter. * Different SQL derived from the same base SQL should reference different parameters. Hovering over a SQL block reference (including a grid page's query result or chart) shows a popup where you can **Override internal parameter references**. The override methods are as follows. | Method {.nowrap} | Description | | --- | --- | | **Override with another parameter** | Replaces the value with another parameter of the same type. | | **Override with a fixed value** | Specifies a fixed value. | | **Don't override** | Follows the [expansion rules](../doc-page/sql-block#param-in-sql-ref) (for example, a notebook-wide parameter uses the referencing page's value). | For how to insert a reference and its expansion settings (**Don't wrap in parentheses** / **Add alias at the end**), see [Referencing SQL blocks](../doc-page/sql-block#sql-block-ref). ## Syncing parameter values {#sync} In a **notebook**, parameter values and run results are synced between users. Use [Version](../version) if you want to avoid concurrent edits. In **Version** and **interactive reports**, parameter changes aren't synced between users; they only apply to the user who made the change. In these features, parameter changes are also synced to the URL (see [Specifying values from a URL](./url)). ## Syncing across report pages {#report-page-sync} Enabling **Sync parameter changes across pages** when publishing a report syncs changes to notebook-wide parameters across published pages. Page-specific parameters aren't linked. See [Report](../sharing/report/overview) for details. --- --- url: 'https://docs.codatum.com/features/notebook/parameter/types.md' description: Parameter types and zero values --- # Types and data types Parameters are classified by their input form type and data type. ## Parameter list and zero values {#types} The list of parameter types, their data types, and the zero value expanded into SQL when a value is unset, are as follows. Multi-input / multi-select types are arrays, but their zero value expands as an empty string `''`. | Type {.nowrap} | Type | Zero value | | --- | --- | --- | | [Text input](#text-input) | STRING | `''` | | [Text select](#text-select) | STRING | `''` | | [Text multi input](#text-multi-input) | STRING\[] | `''` | | [Text multi select](#text-multi-select) | STRING\[] | `''` | | [Number input](#number-input) | NUMBER | `0` | | [Number select](#number-select) | NUMBER | `0` | | [Date input](#date-input) | DATE | `'1970-01-01'` | | [Date range](#date-range) | \[DATE, DATE] | Both start and end are `'1970-01-01'` | | [Checkbox](#checkbox) | BOOLEAN | `false` | See [Usage patterns in SQL](./sql-patterns) for how to use the zero value to write an optional filter. ## Common settings {#common-settings} In addition to type-specific settings, many parameters support the following. | Item {.nowrap} | Description | | --- | --- | | **Description** | Shown as a tooltip next to the parameter name. | | **Placeholder** | The placeholder text shown in the input form. | ## Text input {#text-input} A field for entering a single string. * Expanded in SQL as an escaped string (for example: `'val1'`). * The zero value is `''`. ## Text multi input {#text-multi-input} A field for entering multiple strings. * Expanded in SQL as a comma-separated, escaped string (for example: `'val1', 'val2'`). * The zero value is `''`. ## Text select {#text-select} A dropdown for choosing a single string from candidates. * See [Generating dynamic options](./dynamic-options) for how candidates are generated. * Expanded in SQL as an escaped string. * The zero value is `''`. ## Text multi select {#text-multi-select} A dropdown for choosing multiple strings from candidates. * See [Generating dynamic options](./dynamic-options) for how candidates are generated. * Expanded in SQL as a comma-separated, escaped string (for example: `'val1', 'val2'`). * The zero value is `''`. * You can select up to 1,000 values (see [Limits](../../../reference/limits#fixed-limits)). ## Number input {#number-input} A field for entering a single number. | Item {.nowrap} | Description | | --- | --- | | **Min** | The lower bound of the input value. | | **Max** | The upper bound of the input value. | | **Step** | The increment step for input. | * Expanded in SQL as a number. * The zero value is `0`. ## Number select {#number-select} A dropdown for choosing a single number from candidates. * See [Generating dynamic options](./dynamic-options) for how candidates are generated. * The zero value is `0`. ## Date input {#date-input} A field for choosing a single date. You can select from a calendar or enter the date directly. ### Settings | Item {.nowrap} | Description | | --- | --- | | **Unit** | **Day** / **Week** / **Month** / **Year**. **Day** if unspecified. | | **Unit reference point** | When **Unit** is week, month, or year, chooses whether the value is normalized to the start or end of the period. Start if unspecified. The label changes based on the unit, such as **Start of week** / **End of week**. | | **Start of week** | When **Unit** is day or week, chooses the day of the week used as the week boundary. Sunday if unspecified. | | **Relative valid range** | Restricts the selectable range of past/future days relative to today. | | **Absolute valid range** | Restricts the selectable range using a lower and upper bound date. | The breakdown of **Relative valid range** is as follows. | Item {.nowrap} | Description | | --- | --- | | **Days before today** | Dates before this many days can't be selected. Example: entering `90` disallows dates more than 90 days in the past. | | **Days after today** | Dates after this many days can't be selected. Example: `0` disallows tomorrow and later; `-1` disallows today and later. | The breakdown of **Absolute valid range** is as follows. | Item {.nowrap} | Description | | --- | --- | | **Lower bound date** | Dates before this date can't be selected. | | **Upper bound date** | Dates after this date can't be selected. | ### Expansion * Expanded in SQL as a string in `YYYY-MM-DD` format (for example: `'2024-01-01'`). * The zero value is `'1970-01-01'`. * The default value can be set to a [relative date](./relative-date). If **Unit** is week, month, or year, the selected value is normalized to the start or end of the period according to **unit anchor**. For example, with unit "week," anchor "start," and start of week "Monday," the value becomes that week's Monday. ## Date range {#date-range} Specifies a start date and end date as a pair. The settings are the same as [date input](#date-input), except **unit anchor** isn't shown for date range; the start date is always normalized to the start of the period, and the end date to the end of the period. For example, if **Unit** is **Month** and you select April–May 2026, the value becomes `["2026-04-01", "2026-05-31"]`. Referencing this in SQL differs from the `{{label}}` notation of other types; the start and end dates are specified separately. * Start date: `{label}.StartDate` * End date: `{label}.EndDate` The zero value for both start and end dates is `'1970-01-01'`. The default value can be set to a [relative date](./relative-date). ## Checkbox {#checkbox} A checkbox for toggling a boolean value. * Expanded in SQL as `true` or `false`. * The zero value is `false`. --- --- url: 'https://docs.codatum.com/features/notebook/parameter/sql-patterns.md' description: How to write filters and branches based on parameter values --- # Usage patterns in SQL Parameters aren't a templating language; they're embedded as regular SQL values. Express conditional branching or repetition using SQL syntax such as `CASE` or `IN`. See [Escaping and dynamic references](./escape-and-dynamic-reference) for details on escaping. :::: tip ::: v-pre The `{{label}}` notation below is used for explanation. On screen, it's shown as a labeled reference chip. ::: :::: ## Optional filter {#optional-filter} When a value is unset, the [zero value](./types#types) is expanded. By removing the filter when the value equals the zero value, you can make it function as "fetch all" when unset. ```sql SELECT order_id, product_name, ordered_at FROM orders WHERE -- Start date: don't filter by the lower bound if it's the zero value ('1970-01-01') CASE WHEN {{start_date}} = '1970-01-01' THEN TRUE ELSE ordered_at >= {{start_date}} END -- End date: don't filter by the upper bound if it's the zero value ('1970-01-01') AND CASE WHEN {{end_date}} = '1970-01-01' THEN TRUE ELSE ordered_at <= {{end_date}} END -- Product name: don't filter by product name if it's the zero value ('') AND CASE WHEN {{product_name}} = '' THEN TRUE ELSE product_name LIKE '%{{product_name}}%' END ``` You can also write it as follows, with the same effect. ```sql SELECT * FROM orders WHERE 1 = 1 AND (order_date >= {{start_date}} OR {{start_date}} = '1970-01-01') AND (status = {{status}} OR {{status}} = '') ``` ## Branching by value {#conditional} Switch the selected column or calculation based on a parameter's value. ```sql SELECT order_id, CASE {{region}} WHEN 'EU' THEN amount * 1.20 ELSE amount END AS final_price FROM orders ``` ```sql SELECT CASE {{granularity}} WHEN 'daily' THEN DATE_TRUNC('day', timestamp) WHEN 'weekly' THEN DATE_TRUNC('week', timestamp) ELSE DATE_TRUNC('month', timestamp) END AS period FROM events ``` The following is an example of using a checkbox to switch which table is referenced. ```sql SELECT * FROM ( SELECT sensitive_column AS data FROM sensitive_data WHERE {{is_admin}} = TRUE UNION ALL SELECT public_column AS data FROM filtered_data WHERE {{is_admin}} = FALSE ) t ``` ## Selecting multiple values {#multi-value} [Text multi input](./types#text-multi-input) and [text multi select](./types#text-multi-select) expand as a comma-separated string. Use them together with `IN`. ```sql SELECT * FROM sales WHERE metric_name IN ({{selected_metrics}}) ``` The following aggregates only the selected metrics. ```sql SELECT SUM(CASE WHEN 'revenue' IN ({{selected_metrics}}) THEN revenue ELSE NULL END) AS revenue_total, SUM(CASE WHEN 'cost' IN ({{selected_metrics}}) THEN cost ELSE NULL END) AS cost_total, SUM(CASE WHEN 'profit' IN ({{selected_metrics}}) THEN profit ELSE NULL END) AS profit_total FROM sales ``` ## Dynamic identifiers {#dynamic-identifier} Placing a parameter inside quotes lets you dynamically generate identifiers such as table or column names. See [Escaping and dynamic references](./escape-and-dynamic-reference#dynamic-reference) for how to write these and points to watch for. --- --- url: >- https://docs.codatum.com/features/notebook/parameter/escape-and-dynamic-reference.md description: Escaping of parameter values and dynamic generation of identifiers --- # Escaping and dynamic references How a parameter is escaped depends on where it's placed within the SQL. This mechanism helps prevent SQL injection, and can also be used to dynamically generate identifiers such as table or column names. ## String parameters in a normal context Parameters are expanded escaped as strings. The escaping follows the SQL syntax of the selected connection. ```sql -- If the parameter value is user's "data" WHERE name = {{str_param}} -> WHERE name = 'user\'s \"data\"' -- If the parameter value is O'Reilly's "Book" SELECT name = {{company}} -> SELECT name = 'O\'Reilly\'s \"Book\"' ``` ## String parameters within a quoted context If a parameter is placed inside single quotes, double quotes, backticks, or similar, only the inner content is escaped so the outer quote isn't broken. Escaping follows the connection's SQL syntax. The following is an example for a BigQuery connection. ```sql -- Inside double quotes (escapes both " and ') -- If the parameter value is user"s 'data' SELECT "{{str_param}}" as alias -> SELECT "user\"s \'data\'" as alias -- Inside single quotes (escapes both " and ') -- If the parameter value is user"s 'data' SELECT '{{str_param}}' as alias -> SELECT 'user\"s \'data\'' as alias -- Inside backticks (escapes only `) -- If the parameter value is user"s 'data` SELECT `{{str_param}}` as alias -> SELECT `user"s 'data\`` as alias ``` ## Special handling for date parameters * In a normal context, a date expands as a string in `YYYY-MM-DD` format. * For BigQuery connections, a date placed inside backticks expands as `YYYYMMDD` (no hyphens). ```sql -- BigQuery connection example -- Normal date parameter SELECT {{date_param}} as normal -> SELECT '2024-10-02' as normal -- A date inside quotes follows the same escaping rules SELECT '{{date_param}}' as single_quote -> SELECT '2024-10-02' as single_quote SELECT "{{date_param}}" as double_quote -> SELECT "2024-10-02" as double_quote -- Special case: generating a table name in BigQuery SELECT * FROM `table_{{date_param}}` -> SELECT * FROM `table_20241002` ``` ## Numeric and boolean parameters Numeric and boolean parameters aren't escaped; they're expanded as-is. ## Generating dynamic references {#dynamic-reference} Placing a parameter inside quotes lets you dynamically generate identifiers such as table or column names. ```sql -- Dynamic table name SELECT * FROM `table_{{table_suffix}}` -> SELECT * FROM `table_sales_2024` -- Dynamic field selection SELECT "column_{{field_type}}" -> SELECT "column_revenue" ``` ::: warning Escaping is applied so the syntax doesn't break based on the surrounding quotes. However, **a text parameter can contain any string**. Depending on how the SQL is written, this could unintentionally reference an unexpected table or column. For dynamic identifier generation, consider mitigations such as fixing a prefix or suffix, or writing the SQL so it fails for unexpected values. ::: --- --- url: 'https://docs.codatum.com/features/notebook/parameter/relative-date.md' description: Relative date defaults for date parameters --- # Relative dates You can set a relative date as the default value of a [date input](./types#date-input) or [date range](./types#date-range). Values are defined as an offset from a reference date, such as "today," "yesterday," or "last week." The unit of the offset follows the parameter setting's **unit** (day / week / month / year). For example, when **unit** is **day**, an offset of `0` means today and `-1` means yesterday. When **unit** is **week**, an offset of `0` means this week and `-1` means last week. As described in [Resolving values and default values](./overview#value-resolution), a relative date is calculated into a concrete date and written into the current value when reset. It isn't recalculated automatically on every run. ## Configuring 1. Open the menu at the top right of the parameter's input form. 2. Under **Default value**, choose **Relative date** or **Relative date range**. 3. Specify the **offset** (for date range, **lower bound offset** / **upper bound offset**). ## When relative dates are calculated A relative date is calculated when the parameter value is reset to its default. When this is applied differs by feature, as follows. ### Notebook Applied on the following operations. * **Reset parameter values to default** for the whole form. * **Reset to default value** for an individual parameter. ::: tip In a notebook, parameter changes are shared in real time with other users. Resetting to the default value requires an explicit operation. Simply opening a notebook doesn't recalculate relative dates. ::: ### Public link Relative dates aren't available, since parameters can't be changed. See [Public link](../sharing/public-link/overview) for details. ### Report With the following publish settings, relative dates are applied when the report is opened. * Choose **Interactive report** as the report type. * Enable **Enable auto-run**, and also enable **Use parameter default values**. If **Use parameter default values** is disabled, the parameter value is the value at the time of publishing. Resetting from the input form behaves the same as in a notebook. ::: tip Parameter changes in a report aren't shared with other users. ::: See [Report](../sharing/report/overview) for details. ### Signed embed {#signed-embed} With the following conditions, relative dates are applied when the signed embed is opened. * The parameter is set as a client-side parameter (not a server-side parameter). * For the client-side parameter, the setting is configured to use the parameter's default value as the initial value. If this setting is disabled, the parameter value is the value at the time of publishing. Relative dates aren't available for server-side parameters. If you need to specify a date on the server side, you need to calculate the relative date separately. Resetting from the input form behaves the same as in a notebook. However, a parameter whose input form is hidden isn't subject to reset, so its relative date isn't recalculated. ::: tip Parameter changes in a signed embed aren't shared with other users. ::: See [Signed embed](../sharing/signed-embed/overview) for details. ## Reference time for calculation Relative dates are calculated based on the browser's current time. The timezone follows the browser's setting. Because of this, the resulting date for the same moment might differ depending on timezone. --- --- url: 'https://docs.codatum.com/features/notebook/parameter/dynamic-options.md' description: How to build options for select-type parameters --- # Generating dynamic options For [text select](./types#text-select), [text multi select](./types#text-multi-select), and [number select](./types#number-select), you can generate options in the following ways. ## Fixed list Use this when choosing from fixed values. * Setting: **CSV text**. * Each item is separated by a newline. * To add a display name, write it on the same line, separated by a comma (`,`). ```csv value1,Display name1 value2,Display name2 ``` ## Table Use this to generate options from a specific table's column. | Setting {.nowrap} | Content | | --- | --- | | Table | The table to fetch values from. | | Column for options | The column used as the option's value. | | Column for display name | The column used as the display label (optional; the value is used as the display name if omitted). | SQL against the table is run frequently, to narrow results as the user types. Specify a table with few rows. ## Query result Use this to generate options from the run result of a specified SQL query. | Setting {.nowrap} | Content | | --- | --- | | Connection | The connection to run the SQL on. | | SQL | The SQL that returns the options. If it returns multiple columns, the first column is the value, and the second (if any) is the display label. | Because the options SQL runs frequently, avoid SQL that's slow or consumes a lot of resources. You can also use parameter references within the SQL. For example, you can generate sub-category options based on a major-category parameter. Enabling **Reset if a referenced parameter changes** resets the selected value to default when a dependent parameter changes. SQL that generates options for a **notebook-wide** parameter can't reference **page-specific** parameters, since that would break cross-page references. SQL that generates options for a page-specific parameter can reference both notebook-wide and page-specific parameters. ## When the SQL runs When options come from a table or SQL, fetching happens at the following times. 1. **On page load**: only parameters currently in use on that page are initialized, and their corresponding SQL runs. SQL for unused parameters doesn't run. 2. **On first opening the dropdown**: fetched when the parameter's input form is focused and the dropdown menu opens. 3. **While typing a search**: fetched when narrowing option candidates by typing text in the parameter's input form (if all options have already been fetched, narrowing happens within the fetched options). ## Cache Options from a table or SQL are cached as follows. * Cached on the backend for up to 30 minutes. * Identical SQL (including parameter values) uses the cache. * The frontend also keeps an in-memory cache for the duration of the session. Repeatedly opening the dropdown avoids re-running the same SQL within the cache period. --- --- url: 'https://docs.codatum.com/features/notebook/parameter/url.md' description: Specifying parameter values through URL query parameters --- # Specifying values from a URL When creating an external link, you can override a parameter's value by adding it to the URL. ## Applicable features The following features let you specify parameters from a URL. With these features, the URL updates each time you change a parameter, so sharing the URL also shares the parameter values. * Notebook [versions](../version) * [Reports](../sharing/report/overview) * Applies to **interactive reports**. * If **Auto-run** is enabled, the report runs automatically after merging in the URL-specified parameters. * Even if **Use parameter default values** is enabled, **parameters specified in the URL take priority** (they're reset to default first, and then the URL-specified values are applied). ## How to specify Parameters are synced with the `cdm.params` query parameter in the URL. The format is as follows. ```typescript // Keyed by page ID so values are retained across page navigation type Params = { [pageId: string]: { [paramId: string]: string } }; // Each value is a JSON.stringify'd string // pageId / paramId are actually IDs like 68783eb9c4b4b71483a1d617 const params: Params = { page1: { param1: JSON.stringify('value1'), param2: JSON.stringify(123), }, page2: { param3: JSON.stringify(true), param4: JSON.stringify(['value1', 'value2']), }, }; const query = `?cdm.params=${encodeURIComponent(JSON.stringify(params))}`; ``` ## Shortcut format If `cdm.params` is hard to construct directly, you can also use the `cdm.params.${paramId}` format. If both are present, `cdm.params.${paramId}` takes priority, and the merged result is reflected as a new `cdm.params` in the URL. ```typescript const paramId = 'param1'; // JSON.stringify isn't needed for the shortcut format (but encodeURIComponent is) const value = 'string_value'; const query = `?cdm.params.${paramId}=${encodeURIComponent(value)}`; // Specifying an empty string clears that parameter const queryEmpty = `?cdm.params.${paramId}=`; ``` ## How to specify values How to specify values differs by parameter type. `JSON.stringify` isn't needed for the shortcut format, but `encodeURIComponent` is still needed when placing the value in the URL. | Type | Specifying via `cdm.params` | Shortcut format | | --- | --- | --- | | Text input / Text select | `JSON.stringify("string_value")` | `string_value` | | Text multi input / Text multi select | `JSON.stringify(["item1", "item2"])` | `item1,item2` | | Number input / Number select | `JSON.stringify(123)` | `123` | | Date input | `JSON.stringify("2025-01-01")` | `2025-01-01` | | Date range | `JSON.stringify(["2025-01-01", "2025-01-02"])` | `2025-01-01,2025-01-02` | | Checkbox | `JSON.stringify(true)` or `JSON.stringify(false)` | `true` or `false` | * For array types, use `,` as the separator in the shortcut format. * Date input and date range use `YYYY-MM-DD` format. * An invalid value results in an error screen. --- --- url: 'https://docs.codatum.com/features/notebook/chart/overview.md' description: >- Overview of the chart feature, which aggregates and processes SQL results into graphs and tables --- # Chart A chart aggregates and processes SQL run results, then renders them as a graph or table. You can use charts on [doc pages](../doc-page/overview) and [grid pages](../grid-page/overview). Charts are rendered in the following flow. ```mermaid flowchart LR sqlExec[Fetch SQL run results] modeling[Process based on data modeling] process[Process with SQL or in-memory] render[Render chart (up to 1000 rows)] sqlExec --> modeling --> process --> render ``` 1. Fetches the run results of the SQL specified as the data source. 2. Processes the data based on the chart's **basic settings** (dimensions, metrics, source filter, and so on). 3. Processes the data in-memory if the conditions are met, or with SQL otherwise. 4. Renders the chart based on the processed result (up to 1000 rows) and the **advanced settings**. See [Concepts](./concept/overview) for details. ## Key features * [Concepts](./concept/overview): how rendering works, data modeling, and in-memory processing * [Dimensions and metrics](./concept/dimension-metrics): units of aggregation and aggregation methods * [Filter, sort, and limit](./concept/filter-sort-limit): source filter, sort, row limit, and the difference between group by and frame * [Common settings](./common-settings/overview): frame, value formatting, reference lines, trends, statistics, and more * [Explorer](../explorer): exploring data sources and adding charts * [Cross filter](../grid-page/cross-filter): linking charts on a grid page ## Chart types {#chart-types} | Type {.nowrap} | Typical use | | --- | --- | | [Big Number](./big-number) | A single indicator or gauge display using a metric and an optional secondary metric. | | [XY Chart](./xy-chart) | Aggregates a Y value (metric) against an X value (dimension). Line, bar, area, scatter, and more. | | [Radial Chart](./radial-chart) | Aggregates a value against a label. Pie, donut, and radar charts. | | [XYZ Chart](./xyz-chart) | Aggregates a Z value (metric) against X and Y values (dimensions). Scatter, bubble, and heatmap. | | [Hierarchy Chart](./hierarchy-chart) | Aggregates a value against a hierarchy (dimension). Tree, treemap, sunburst, and more. | | [Graph Chart](./graph-chart) | Aggregates a weight against source and target. Network and Sankey diagrams. | | [Funnel Chart](./funnel-chart) | Aggregates a value against a label to visualize a step-by-step process. | | [Waterfall Chart](./waterfall-chart) | Shows the cumulative increase and decrease of a value against a label. | | [Table Chart](./table-chart) | Displays data as a table, either as raw rows or aggregated. | | [Pivot Table](./pivot-table) | Cross-tabulates a value (metric) against rows and columns (dimensions). | | [Text Panel](./text-panel) | Displays the first value of a selected column as text. | | [Map Chart](./map-chart) | Visualizes geographic data using latitude/longitude, geohash, geocode, or GeoJSON. | | [Word Cloud](./word-cloud) | Aggregates a value against a word to visualize word weight. | Each page includes details on drawing types and settings. --- --- url: 'https://docs.codatum.com/features/notebook/chart/concept/overview.md' description: Overview of how charts are rendered and how data modeling works --- # Chart concepts A chart is a feature that specifies how to process and render the SQL run result of a data source. Settings are split between **basic settings** and **advanced settings** on the chart edit screen. * **Basic settings**: processing the data for rendering, such as dimensions, metrics, and the source filter. * **Advanced settings**: adjusting the appearance, such as axes, legend, value format, and frame display. ## Rendering flow {#pipeline} Charts are rendered in the following flow. ```mermaid flowchart LR source[SQL run result of the data source] settings[Data modeling from basic settings] decide{Meets the conditions for in-memory processing?} inmem[Process in the browser] sqlProc[Run processing SQL] draw[Render based on advanced settings (up to 1000 rows)] source --> settings --> decide decide -->|Yes| inmem --> draw decide -->|No| sqlProc --> draw ``` 1. Fetches the run result of the SQL specified as the data source. 2. Prepares data for rendering based on the dimensions, metrics, source filter, and other **basic settings**. 3. If all of the following conditions are met, performs equivalent processing in the browser without issuing new SQL (in-memory processing): * The data source's run result has 1000 rows or fewer. * **Custom SQL** isn't specified. * **Disable in-memory processing** is off. 4. Renders the chart based on the processed result (up to 1000 rows) and **advanced settings**. If the data to render exceeds 1000 rows, the screen shows "Rendered with up to 1000 rows of data." See [Filter, sort, and limit](./filter-sort-limit#limit) for the row limit. ## Data modeling {#data-modeling} A chart structures and processes the SQL run result using the following components. | Component {.nowrap} | SQL equivalent | Role | | --- | --- | --- | | [Dimension](./dimension-metrics#dimension-metric) | `GROUP BY` clause | The axis used to split data. | | [Metric](./dimension-metrics#dimension-metric) | Aggregate functions such as `SUM()` | The numeric value being aggregated. | | [Source filter](./filter-sort-limit#source-filter) | `WHERE` clause | Narrows down the data to aggregate. | For example, to show "total sales by category" as a bar chart, you'd specify category as the dimension and sales as the metric (aggregation method `SUM`). The number and role of these components that you can specify varies by chart type. * **Dimension**: XY Chart's **X value**, Radial Chart's **Label**, Map Chart's latitude/longitude, and so on. * **Metric**: XY Chart's **Y value**, Radial Chart's **Value**, Big Number's **Metric**, and so on. * **Source filter**: for example, a condition to render only a specific category. See [Dimensions and metrics](./dimension-metrics) for details on dimensions and metrics. ## In-memory processing {#in-memory-processing} For chart data processing, if the data source's SQL run result has 1000 rows or fewer and **Custom SQL** isn't specified, equivalent processing is done in the user's browser instead of running new SQL. This processing is called "in-memory processing," and can be disabled with **Disable in-memory processing** in a chart's **basic settings**. If you use **Custom SQL**, in-memory processing isn't available, and the toggle isn't shown. See [Pivot Table](../pivot-table#processing-diff) for an example of how results differ depending on whether in-memory processing was used. --- --- url: 'https://docs.codatum.com/features/notebook/chart/concept/dimension-metrics.md' description: 'Units of aggregation, aggregation methods, and date processing for charts' --- # Dimensions and metrics Chart data aggregation is built around the concepts of **dimensions** and **metrics**. On the chart edit screen's **basic settings**, you specify these as fields appropriate to the chart type (**X value**, **Label**, **Metric**, and so on). ## Dimensions and metrics {#dimension-metric} * **Dimension**: a value used to group data. It determines "what to split by," such as category or date. * **Metric**: an aggregated numeric value. It determines "what to measure," such as sum, average, or count. In SQL terms, a dimension corresponds to a column used in `GROUP BY`, and a metric corresponds to a column computed by an aggregate function such as `SUM()` or `COUNT()`. When adding or editing a field, you set the following items. | Item {.nowrap} | Description | | --- | --- | | **Source column** | Select a column from the data source. | | **Display name** | Specify a name used in the legend, tooltip, and so on. | | **Aggregation method** | Specified for metrics. | | **Custom SQL** | Specify a SQL expression directly instead of selecting a column. | ## Metric aggregation method {#aggregation} For a metric's **aggregation method**, choose one of the following. The on-screen options are shown as English function names. | Aggregation method {.nowrap} | Content | | --- | --- | | `SUM` | Sum. | | `AVG` | Average. | | `COUNT` | Count. | | `COUNT_UNIQUE` | Unique count. | | `MAX` | Maximum. | | `MIN` | Minimum. | | `ANY_VALUE` | Any single value. | If you use **Custom SQL**, enter SQL that includes an aggregate function returning a number, such as `SUM(sales)`. ## Date processing {#date-transform} When you select a date or datetime column for a dimension (**X value**, **Group by**, **Frame**, and so on), you can configure **date processing** or **datetime processing**. Configure it as follows. 1. On the chart edit screen's **basic settings**, select a date or datetime column. 2. Open **Edit dimension** and choose the transform type and unit. ### Transform types | Item {.nowrap} | Description | | --- | --- | | **None** | No processing. | | **Truncate** | Truncates the value to the specified unit. Example: truncating `2025-01-15` by `MONTH` → `2025-01-01`. Used for monthly, weekly, or yearly aggregation. | | **Extract** | Extracts only a specific part of the date. Example: extracting `DAY` from `2025-01-15` → `15`. Used to analyze patterns by day of month or time of day (the same day in different months is aggregated together). | The unit for **truncate unit** / **extract unit** is shown on screen in English, such as `YEAR` / `MONTH` / `WEEK` / `DAY` / `HOUR` / `MINUTE`. For datetime with a timezone, you can also specify a **timezone**. ### Bucketing For numeric columns, you can enable **Bucketing** and specify a **bucket size**. This groups numbers into intervals of the specified width. ## Group by {#group-by} Some charts support **Group by**. It splits the **series** within the same chart based on the value of the specified column. * **Group by**: splits series (for example, by color) within the same chart. * **Frame**: splits the chart itself by a column's value. See [Filter, sort, and limit](./filter-sort-limit#group-vs-frame) and [Frame](../common-settings/frame) for the difference from frame. --- --- url: 'https://docs.codatum.com/features/notebook/chart/concept/filter-sort-limit.md' description: 'Source filter, sort, row limit, and the difference between group by and frame' --- # Filter, sort, and limit A chart's **basic settings** let you control the filtering, order, and row count of the data to render. Some charts let you set the order of series separately from the order of the data. ## Source filter {#source-filter} **Source filter** lets you narrow down the data source and limit the data to render. This condition is applied before aggregation. A condition combines a column, an operator, and a value. The operators are shown on screen as follows. | Operator {.nowrap} | Typical use | | --- | --- | | `=` / `!=` | Equal / not equal. | | `>` / `>=` / `<` / `<=` | Comparison. | | `IS NULL` / `IS NOT NULL` | NULL check. | | `IN` / `NOT IN` | Matches one of multiple values. | | `BETWEEN` | Range. | | `LIKE` | Pattern match. | You can also write a condition expression directly with **Custom SQL**. Conditions can be combined with AND / OR. ## Sort {#sort} Depending on the chart type, you can set **Sort**, **X-axis sort**, **Row sort** / **Column sort**, and so on. The sort types are as follows. | Type {.nowrap} | Description | | --- | --- | | **Value** | Sorts by the metric's value. Order is **ascending** / **descending**. | | **Label** | Sorts by the dimension's value. Order is **ascending** / **descending**. | | **Custom** | Sorts by a specified column or aggregation. | For XY Chart's **Value** sort, the condition specified for the first **Y value** in **Series** is used. For some chart types, the meaning of the sort affects the rendering. For example, in Funnel Chart, the sort type changes the basis for the ratio calculation. See each chart type's page for details. ## Group sort {#group-sort} For charts that have **Group by**, **Group sort** lets you specify the order of series and the legend. | Type {.nowrap} | Description | | --- | --- | | **Label** | Ascending or descending order of the value specified in group by. | | **Custom** | Ascending or descending order of a specified column. Specify a column that's uniquely determined for the grouped value (for example: group by user name → sort by user ID). | ## Limit rows {#limit} **Limit rows** restricts the number of rows of data to render, from 1 to 1000. The data to render is capped at 1000 rows. If the limit is exceeded, the message "Rendered with up to 1000 rows of data" is shown. Combining a row limit with sort lets you visualize the top N items. ## Group by vs. frame {#group-vs-frame} Even when using the same dimension, **group by** and **frame** produce different appearances. | Item {.nowrap} | Group by | Frame | | --- | --- | --- | | On-screen label | **Group by** | **Frame** | | Appearance | Splits the series within the same chart (for example, by color). | Splits the chart itself by the column's value. | | Typical use | Comparing within a single figure. | Comparing small charts side by side. | ```mermaid flowchart LR groupBy[Group by] frame[Frame] series[Split series within the same chart] multi[Split the chart itself into multiple displays] groupBy --> series frame --> multi ``` See [Frame](../common-settings/frame) for the frame layout (**Timeline** / **Grid**). --- --- url: 'https://docs.codatum.com/features/notebook/chart/common-settings/overview.md' description: >- Display settings shared across charts, such as frame, value formatting, and analytics display --- # Common chart settings These are display settings that many charts can use in common. They're mostly found in **advanced settings**, but the **frame** setting is in **basic settings**. ## Key features * [Frame](./frame): split a chart's display by a column's value * [Value formatting](./value-format): display format for numbers and dates * [Reference lines, trends, and statistics](./analytics): analytics displays available on XY Chart and XYZ Chart For settings specific to axes, series, and so on for each chart type, see that chart type's page. ## Axis label max width {#axis-label-max-width} For some charts, the axis settings in **advanced settings** include **Axis label max width (px)**, which limits the display width of each axis's labels. Use this when you want to truncate long label text. --- --- url: 'https://docs.codatum.com/features/notebook/chart/common-settings/frame.md' description: A frame that splits a chart's display by a column's value --- # Frame {#frame-feature} For some charts, specifying a column in **Frame** under **basic settings** splits the chart's display by that column's value. Choose **Timeline** or **Grid** for **Frame layout** to control how it's displayed. The frame feature makes it easier to compare changes over time or across categories. See [Filter, sort, and limit](../concept/filter-sort-limit#group-vs-frame) for the difference from **group by** (splitting series within the same chart). ## Examples * Compare a pie chart of sales by category side by side for each gender (set **Frame** to gender, **Frame layout** to **Grid**). * Switch through a timeline to see the trend of sales by year (set **Frame** to year). ## Scale {#scale} To make it easier to compare across frames, the Y-axis range, bubble size scale, heatmap color scale, and so on are shared across all frames by default. You can change this behavior with **advanced settings** > **Frame** > **Independent scale**. ## Timeline layout {#timeline} When **Frame layout** is **Timeline** (including when unspecified), a frame control appears at the bottom of the chart, letting you switch frames manually or play an animation. Frames are ordered by the ascending value of the column. **Advanced settings** > **Frame** lets you configure the following. | Item {.nowrap} | Description | | --- | --- | | **Autoplay** | Automatically switches between frames. | | **Play in reverse** | Starts from the last frame and plays in reverse order. | | **Play interval (sec)** | The display duration of one frame. | ![XY Frame Timeline](/chart-capture/xy-frame-light.png "XY Chart"){.light-only .chart-capture} ![XY Frame Timeline](/chart-capture/xy-frame-dark.png "XY Chart"){.dark-only .chart-capture} ![Graph Frame Timeline](/chart-capture/graph-frame-light.png "Graph Chart"){.light-only .chart-capture} ![Graph Frame Timeline](/chart-capture/graph-frame-dark.png "Graph Chart"){.dark-only .chart-capture} ## Grid layout {#grid} When **Frame layout** is **Grid**, all frames are displayed as a grid (up to 16). The number of columns is adjusted **automatically** by default, arranging frames as close to a square shape as possible (for example, 3 items → 2 columns × 2 rows, 5 items → 3 columns × 2 rows). You can specify the number of columns in **advanced settings** > **Frame** > **Columns**. ![XY Frame Grid](/chart-capture/xy-frame-grid-light.png "XY Chart"){.light-only .chart-capture} ![XY Frame Grid](/chart-capture/xy-frame-grid-dark.png "XY Chart"){.dark-only .chart-capture} ![Radial Frame Grid](/chart-capture/radial-frame-grid-light.png "Radial Chart"){.light-only .chart-capture} ![Radial Frame Grid](/chart-capture/radial-frame-grid-dark.png "Radial Chart"){.dark-only .chart-capture} The fixed limit is also documented in [Limits](../../../../reference/limits#fixed-limits). ## Supported charts {#supported-charts} | Chart {.nowrap} | Support | | --- | --- | | [XY Chart](../xy-chart) | Supported. | | [Radial Chart](../radial-chart) | Supported. | | [XYZ Chart](../xyz-chart) | Supported. | | [Hierarchy Chart](../hierarchy-chart) | Partially supported (bar chart / drill down isn't supported). | | [Graph Chart](../graph-chart) | Supported. | | [Funnel Chart](../funnel-chart) | Supported. | | [Waterfall Chart](../waterfall-chart) | Supported. | | [Word Cloud](../word-cloud) | Supported. | --- --- url: >- https://docs.codatum.com/features/notebook/chart/common-settings/value-format.md description: The formatter used for numbers and dates in charts --- # Value formatting The format of values and labels shown in a chart is, by default, optimized based on your account's language setting. You can change it from **value format** in the chart's **advanced settings**. If you've changed the formatter, its setting takes priority regardless of the language setting. ## Where to specify it For example, on XY Chart, you can specify a formatter in the following places. * Axis labels * **Advanced settings** > **X axis** / **Y axis** > **Value format**. * Values in the tooltip * **Advanced settings** > **Series** > (series name) > **Value format**. * Value labels (if **Value labels** are shown) * **Advanced settings** > **Series** > (series name) > **Value labels** > **Value label format**. Use the button on the left of the input field to switch between the number formatter and the date formatter. The date formatter also offers presets in **Format list**. ## Number formatter {#number-formatter} The number formatter uses [d3-format](https://d3js.org/d3-format) syntax. You can also use the **number formatter builder** to build the display format, precision, digit grouping, and so on. For example, you can specify the following. | Setting {.nowrap} | Number | Formatted result | | --- | --- | --- | | `.0f` | `12345.6789` | `12346` | | `,.1r` | `12345.6789` | `10,000` | | `-.1%` | `0.5` | `50%` | You can also wrap d3-format syntax in `{` and `}`, and add a **prefix** or **suffix** around it (this is a Codatum-specific extension, not part of d3-format itself). | Setting {.nowrap} | Number | Formatted result | | --- | --- | --- | | `{,d} JPY` | `12345.6` | `12,346 JPY` | | `about {,d}%` | `50` | `about 50%` | ## Date formatter {#date-formatter} The date formatter uses [Day.js](https://day.js.org/docs/en/display/format) syntax. For example, you can specify the following. | Setting {.nowrap} | Date | Formatted result | | --- | --- | --- | | `YYYY-MM-DD` | `2025-01-01` | `2025-01-01` | | `YY/M/D` | `2025-01-01` | `25/1/1` | | `MMMM YYYY` | `2025-01-01` | `January 2025` | --- --- url: 'https://docs.codatum.com/features/notebook/chart/common-settings/analytics.md' description: 'Reference lines, trends, and statistics available on XY Chart and XYZ Chart' --- # Reference lines, trends, and statistics On [XY Chart](../xy-chart) and [XYZ Chart](../xyz-chart), you can add the following displays from **advanced settings**. The setting items (**type**, **display**, **trend type**, and so on) are common to both. | Feature {.nowrap} | Content | | --- | --- | | [Reference line](#reference-line) | Shows a guide line or band on an axis. | | [Trend](#trend) | Shows the tendency of a series using regression or a moving average. | | [Statistics](#statistics) | Shows a series' average, median, max, and min as dashed lines. | There are differences in where you open the settings. | Item {.nowrap} | XY Chart | XYZ Chart | | --- | --- | --- | | Reference line | **Advanced settings** > **X axis** / **Y axis** > **Reference line** | Same. Scatter and bubble only (hidden for heatmap). | | Trend / statistics | **Advanced settings** > **Series** > (each Y value's series) > **Trend** / **Statistics** | **Advanced settings** > **Series** > **Trend** / **Statistics**. Scatter and bubble only (hidden for heatmap). | ## Reference line {#reference-line} You can show a guide line or area on a chart, such as a target value, an acceptable range, or a danger zone. Y-axis reference lines are drawn horizontally, and X-axis reference lines are drawn vertically. ![XY Reference Line](/chart-capture/xy-reference-line-light.png "Reference line"){.light-only .chart-capture} ![XY Reference Line](/chart-capture/xy-reference-line-dark.png "Reference line"){.dark-only .chart-capture} ### How to configure 1. In the chart edit screen's **advanced settings**, open the axis (**X axis** / **Y axis**) where you want to show a reference line. 2. Add an item under **Reference line**. 3. Specify the **type** and value. On XYZ Chart, you can only configure **reference line** for scatter and bubble. ### Specification | Item {.nowrap} | Description | | --- | --- | | **Type**: **Line** | Shows a dashed line at a specific value. Specify the position with **Value** (for example, a sales target, a threshold, or a marker for a specific date). | | **Type**: **Band (range)** | Shows a specific range as a semi-transparent band. Specify the range with **Start value** / **End value**. Leaving these blank extends the band to the edge of the chart (for example, an acceptable range, a danger zone, or a caution period). | | **Color** | Choose from **Success** / **Warning** / **Danger**. | | **Label** | The text attached to the reference line. | ## Trend {#trend} You can show a trend line (regression, moving average, and so on) for a series. The trend line is added as a separate series from the original. ![XYZ Trend](/chart-capture/xyz-trendline-light.png "Trend"){.light-only .chart-capture} ![XYZ Trend](/chart-capture/xyz-trendline-dark.png "Trend"){.dark-only .chart-capture} ### How to configure 1. In the chart edit screen, open **advanced settings** > **Series**. * On XY Chart, open the target Y value (series) first, then configure it. * On XYZ Chart, configure it directly under **Series** (scatter and bubble only). 2. Turn on **Trend** > **Display**. 3. Choose a **trend type**. The trend line is shown as a dashed line. Except for **Moving average**, the equation and R² (coefficient of determination) are shown on the chart. You can hide them with **Hide equation** / **Hide R²**. ### Trend types {#trend-types} | Trend type {.nowrap} | Description | Additional setting | | --- | --- | --- | | **Linear** | Shows a linear regression (y = mx + c). | None. | | **Polynomial** | Shows a polynomial regression. | **Polynomial degree** (2–5). | | **Moving average** | Shows a moving average. | **Moving average window size**. | | **Exponential** | Shows an exponential regression (y = ae^(bx)). | None. | | **Logarithmic** | Shows a logarithmic regression (y = a + b ln(x)). | None. | | **Power** | Shows a power regression (y = ax^b). | None. | If there's too little data, or the specified trend type fails to fit, the trend line isn't shown. ## Statistics {#statistics} You can show a series' statistical value as a dashed line. The dashed line's label shows the statistic type and its value. ![XY Statistics](/chart-capture/xy-stats-light.png "Statistics"){.light-only .chart-capture} ![XY Statistics](/chart-capture/xy-stats-dark.png "Statistics"){.dark-only .chart-capture} ### How to configure 1. In the chart edit screen, open **advanced settings** > **Series**. * On XY Chart, open the target Y value (series) first, then configure it. * On XYZ Chart, configure it directly under **Series** (scatter and bubble only). 2. Turn on **Statistics** > **Display**. 3. Choose a **statistic type** (**Average** / **Median** / **Max** / **Min**). ### Difference from trend {#stats-vs-trend} | Characteristic {.nowrap} | Statistics | Trend | | --- | --- | --- | | Display format | Shown as part of the same series. | Added as a separate series (trend line). | | When zooming the chart | Recalculated using only the data in the visible range. | Not recalculated (always based on all data). | | Display on stacked charts | Shown in sync with the target series' stacking. | Not stacked; shown as a separate series. | --- --- url: 'https://docs.codatum.com/features/notebook/chart/big-number.md' description: A chart that displays a key indicator as text or a gauge --- # Big Number Big Number is a chart that displays a key indicator prominently. It aggregates a **metric** (required) and a **secondary metric** (optional) as metrics. In a gauge, the secondary metric becomes the gauge's maximum value. ## Drawing types {#drawing-types} Big Number has two drawing types: **Text** and **Gauge**. ![BigNumber Text](/chart-capture/bignumber-text-light.png "Text"){.light-only .chart-capture} ![BigNumber Text](/chart-capture/bignumber-text-dark.png "Text"){.dark-only .chart-capture} ![BigNumber Gauge](/chart-capture/bignumber-gauge-light.png "Gauge"){.light-only .chart-capture} ![BigNumber Gauge](/chart-capture/bignumber-gauge-dark.png "Gauge"){.dark-only .chart-capture} ## Specification ### Aggregation {#aggregation} Big Number [doesn't use a dimension; it aggregates the selected metric](./concept/dimension-metrics#dimension-metric) and displays it as a single value. | Item {.nowrap} | Role | Notes | | --- | --- | --- | | **Metric** | Metric | Displays the aggregated result as a single value. | | **Secondary metric** | Metric | In gauge mode, this becomes **Secondary metric (gauge max)** and is required. | #### Examples * Show "total sales" as text. * **Metric**: sum of sales. * Show "achievement rate" as a gauge. * **Metric**: sum of actuals. * **Secondary metric (gauge max)**: sum of targets. ### Gauge specification {#gauge} * The gauge's achievement rate (%) is calculated as "metric ÷ secondary metric × 100". * The secondary metric is required and must be a numeric column. ## Tips ### Conditional formatting {#conditional-format} In **advanced settings**, **conditional formatting** lets you change the font color based on the metric's value. For example, if the metric is an achievement rate, you can change the color to a danger color when it's 80 or below, and a success color when it's 100 or above. --- --- url: 'https://docs.codatum.com/features/notebook/chart/xy-chart.md' description: A two-dimensional chart that aggregates a Y-axis value against X-axis items --- # XY Chart XY Chart aggregates a **Y value** (metric) against an **X value** (dimension) and displays the result. You can draw line, bar, area, scatter, and other types individually or as a combination, and use **group by** or **series** to handle multiple series. ## Drawing types {#drawing-types} XY Chart supports the following drawing types, as well as combined charts that mix them. ![XY Line](/chart-capture/xy-line-light.png "Line"){.light-only .chart-capture} ![XY Line](/chart-capture/xy-line-dark.png "Line"){.dark-only .chart-capture} ![XY Bar](/chart-capture/xy-bar-light.png "Bar"){.light-only .chart-capture} ![XY Bar](/chart-capture/xy-bar-dark.png "Bar"){.dark-only .chart-capture} ![XY Stacked Bar](/chart-capture/xy-stackedbar-light.png "Stacked bar"){.light-only .chart-capture} ![XY Stacked Bar](/chart-capture/xy-stackedbar-dark.png "Stacked bar"){.dark-only .chart-capture} ![XY Area](/chart-capture/xy-area-light.png "Area"){.light-only .chart-capture} ![XY Area](/chart-capture/xy-area-dark.png "Area"){.dark-only .chart-capture} ![XY Stacked Area](/chart-capture/xy-stackedarea-light.png "Stacked area"){.light-only .chart-capture} ![XY Stacked Area](/chart-capture/xy-stackedarea-dark.png "Stacked area"){.dark-only .chart-capture} ![XY Percent Bar](/chart-capture/xy-percentbar-light.png "100% stacked bar"){.light-only .chart-capture} ![XY Percent Bar](/chart-capture/xy-percentbar-dark.png "100% stacked bar"){.dark-only .chart-capture} ![XY Scatter](/chart-capture/xy-scatter-light.png "Scatter"){.light-only .chart-capture} ![XY Scatter](/chart-capture/xy-scatter-dark.png "Scatter"){.dark-only .chart-capture} ![XY Bubble](/chart-capture/xy-bubble-light.png "Bubble"){.light-only .chart-capture} ![XY Bubble](/chart-capture/xy-bubble-dark.png "Bubble"){.dark-only .chart-capture} ![XY Percent Area](/chart-capture/xy-percentarea-light.png "100% stacked area"){.light-only .chart-capture} ![XY Percent Area](/chart-capture/xy-percentarea-dark.png "100% stacked area"){.dark-only .chart-capture} ## Specification ### Aggregation {#xy-xyz-diff} XY Chart treats **X value** as a dimension and **Y value** as a metric, aggregating Y for each X and drawing it as a series. See [Dimensions and metrics](./concept/dimension-metrics#dimension-metric) for the concepts behind dimensions and metrics. The difference from [XYZ Chart](./xyz-chart) is that there, both the X value and Y value are dimensions, and the Z value is aggregated for each combination of X and Y. | Item {.nowrap} | Role | Notes | | --- | --- | --- | | **X value** | Dimension | The unit of aggregation (aggregated per X). | | **Y value** | Metric | Specified per **series**. Each metric adds a series. | | **Group by** | Dimension | Splits the series by the value of the specified column. | | **Bubble size** | Metric | Specified only when drawing bubbles. | #### Examples * Show "total sales by month" as a line chart. * **X value**: month. * **Y value**: sum of sales. * Show "total sales by product category" as a bar chart. * **X value**: product category. * **Y value**: sum of sales. ### X-axis specification {#x-axis} In XY Chart, the type of X axis is determined by the **X-axis data type** and the **combination of drawing types**. | X-axis data type {.nowrap} | Drawing type combination | X-axis classification | | --- | --- | --- | | Date/datetime | Any | Time axis | | Numeric | Scatter, bubble, or line only | Numeric axis | | Numeric | Includes bar, area, or stacked | Category axis | | Anything else | Any | Category axis | #### Category axis {#axis-category} On a category axis, even if the specified values are numeric or date/datetime, they're drawn as discrete values at equal intervals. ##### Specifying axis min/max When you specify a min or max on a category axis, the specified value is treated as the index of the data's display order (0th, 1st, 2nd, and so on). | Index {.nowrap} | X-axis value | | --- | --- | | 0th | `1` | | 1st | `10` | | 2nd | `20` | | 3rd | `30` | | ... | ... | | 10th | `100` | In this case, setting the axis max to `10` shows data up to the 10th item, so the X axis is shown up to the value `100`. #### Time axis {#axis-time} On a time axis, the specified date/datetime data is drawn as a continuous time series. * Axis labels are determined dynamically based on the specified date/datetime data. * If the data includes a timezone, it's converted to the browser's timezone for drawing. * Because axis labels are shown based on the browser's timezone, if the browser's timezone doesn't match the data's timezone, the axis labels and data labels might not line up. * Using a datetime type without a timezone avoids the effect of the browser's timezone. #### Numeric axis {#axis-value} On a numeric axis, the specified numeric data is drawn as continuous numeric values. ## Tips ### Specifying multiple series {#multiple-views} When you set multiple series, **Indepedent scale** appears within each series' settings. Turning this on makes that series' Y-axis scale independent, drawn on the right side. You can configure labels and other settings for the independent Y axis in **advanced settings** > **Independent axes**. ![XY Mixed](/chart-capture/xy-mixed-light.png "Independent axes"){.light-only .chart-capture} ![XY Mixed](/chart-capture/xy-mixed-dark.png "Independent axes"){.dark-only .chart-capture} When you set multiple series, **Split by series** appears below the **Series** setting. Turning this on makes each series' Y-axis scale independent and arranges the series vertically. Enabling **Split by series** disables the [frame feature](#frame-feature). It also hides the **Indepedent scale** setting above, since all series are then treated as independent axes. You can configure the Y axis for each series in **advanced settings** > **Independent axes**. ![XY Mixed Split](/chart-capture/xy-mixed-split-light.png "Split by series"){.light-only .chart-capture} ![XY Mixed Split](/chart-capture/xy-mixed-split-dark.png "Split by series"){.dark-only .chart-capture} ### Frame {#frame-feature} XY Chart supports the frame feature. See [Frame](./common-settings/frame#frame-feature) for details. ### Reference lines, trends, and statistics {#analytics} See [Reference lines, trends, and statistics](./common-settings/analytics) for details. --- --- url: 'https://docs.codatum.com/features/notebook/chart/radial-chart.md' description: A chart that visualizes composition ratios or comparisons between items --- # Radial Chart Radial Chart visualizes composition ratios or comparisons between items. It aggregates a **value** (metric) for each **label** (dimension). In a radar chart, you can use **group by** to overlay multiple series for comparison. ## Drawing types {#drawing-types} Radial Chart supports the following drawing types. ![Radial Pie](/chart-capture/radial-pie-light.png "Pie chart"){.light-only .chart-capture} ![Radial Pie](/chart-capture/radial-pie-dark.png "Pie chart"){.dark-only .chart-capture} ![Radial Donut](/chart-capture/radial-donut-light.png "Donut chart"){.light-only .chart-capture} ![Radial Donut](/chart-capture/radial-donut-dark.png "Donut chart"){.dark-only .chart-capture} ![Radial Radar](/chart-capture/radial-radar-light.png "Radar chart"){.light-only .chart-capture} ![Radial Radar](/chart-capture/radial-radar-dark.png "Radar chart"){.dark-only .chart-capture} ## Specification ### Aggregation {#aggregation} Radial Chart [aggregates a value (metric) for each label (dimension)](./concept/dimension-metrics#dimension-metric) and displays the result. | Item {.nowrap} | Role | Notes | | --- | --- | --- | | **Label** | Dimension | Becomes the item name (segment). | | **Value** | Metric | Aggregated for each label. | | **Group by** | Dimension | Splits the series by value (radar chart only). | #### Examples * Show "total sales by product category" as a pie chart. * **Label**: product category. * **Value**: sum of sales. * Compare "customer satisfaction by evaluation item, broken down by department" as a radar chart. * **Label**: evaluation item. * **Value**: average customer satisfaction. * **Group by**: department. ### Specification by drawing type {#drawing-type-details} * Pie and donut charts are drawn as a single series of "label × value". * Radar charts use labels as axes, with the series split by the value of **group by**. ## Tips ### Frame {#frame-feature} Radial Chart supports the frame feature. See [Frame](./common-settings/frame#frame-feature) for details. --- --- url: 'https://docs.codatum.com/features/notebook/chart/xyz-chart.md' description: A chart that aggregates a Z-axis value against X-axis and Y-axis items --- # XYZ Chart XYZ Chart aggregates a **Z value** (metric) against combinations of **X value** and **Y value** (both dimensions) and displays the result. The difference from [XY Chart](./xy-chart) is that the Y side is also a dimension. ## Drawing types {#drawing-types} XYZ Chart supports the following drawing types. ![XYZ Scatter](/chart-capture/xyz-scatter-light.png "Scatter"){.light-only .chart-capture} ![XYZ Scatter](/chart-capture/xyz-scatter-dark.png "Scatter"){.dark-only .chart-capture} ![XYZ Bubble](/chart-capture/xyz-bubble-light.png "Bubble"){.light-only .chart-capture} ![XYZ Bubble](/chart-capture/xyz-bubble-dark.png "Bubble"){.dark-only .chart-capture} ![XYZ Heatmap](/chart-capture/xyz-heatmap-light.png "Heatmap"){.light-only .chart-capture} ![XYZ Heatmap](/chart-capture/xyz-heatmap-dark.png "Heatmap"){.dark-only .chart-capture} ## Specification ### Aggregation {#aggregation} XYZ Chart treats **X value** and **Y value** as dimensions and **Z value** as a metric, aggregating Z for each combination of X and Y. See [Dimensions and metrics](./concept/dimension-metrics#dimension-metric) for the concepts behind dimensions and metrics. | Item {.nowrap} | Role | Notes | | --- | --- | --- | | **X value** | Dimension | Becomes the X axis. | | **Y value** | Dimension | Becomes the Y axis. | | **Z value** | Metric | Specified for bubble and heatmap. | | **Group by** | Dimension | Scatter and bubble only (splits the series). | #### Examples * Show "total sales by product category × region" as a heatmap. * **X value**: product category. * **Y value**: region. * **Z value**: sum of sales. * Show "the relationship between ad spend and sales" as a bubble chart. * **X value**: ad spend. * **Y value**: sales. * **Z value**: profit. ### X-axis specification {#x-axis} In XYZ Chart, how the X and Y axes are treated depends on the drawing type. * For heatmap, both the X and Y axes are category axes. * For scatter and bubble, the X axis is a category, time, or numeric axis depending on the data type, and the Y axis is a numeric axis. For the behavior of each axis (display rules for category, time, and numeric axes), see [X-axis specification](./xy-chart#x-axis) for XY Chart. ## Tips ### Frame {#frame-feature} XYZ Chart supports the frame feature. See [Frame](./common-settings/frame#frame-feature) for details. ### Reference lines, trends, and statistics {#analytics} See [Reference lines, trends, and statistics](./common-settings/analytics) for details. --- --- url: 'https://docs.codatum.com/features/notebook/chart/hierarchy-chart.md' description: A chart that visualizes hierarchical data --- # Hierarchy Chart Hierarchy Chart visualizes data that has a hierarchical structure. You specify a **hierarchy** (one or more dimensions) from the broadest level down, and aggregate an optional **value** (metric) as the weight. ## Drawing types {#drawing-types} Hierarchy Chart supports the following drawing types. ![Hierarchy Tree](/chart-capture/hierarchy-tree-light.png "Tree"){.light-only .chart-capture} ![Hierarchy Tree](/chart-capture/hierarchy-tree-dark.png "Tree"){.dark-only .chart-capture} ![Hierarchy Treemap](/chart-capture/hierarchy-treemap-light.png "Treemap"){.light-only .chart-capture} ![Hierarchy Treemap](/chart-capture/hierarchy-treemap-dark.png "Treemap"){.dark-only .chart-capture} ![Hierarchy Sunburst](/chart-capture/hierarchy-sunburst-light.png "Sunburst"){.light-only .chart-capture} ![Hierarchy Sunburst](/chart-capture/hierarchy-sunburst-dark.png "Sunburst"){.dark-only .chart-capture} ![Hierarchy Bar](/chart-capture/hierarchy-bar-light.png "Bar chart (drill down)"){.light-only .chart-capture} ![Hierarchy Bar](/chart-capture/hierarchy-bar-dark.png "Bar chart (drill down)"){.dark-only .chart-capture} ## Specification ### Aggregation {#aggregation} Hierarchy Chart [aggregates a value (metric) for each level of the hierarchy (dimension)](./concept/dimension-metrics#dimension-metric) and draws the hierarchical structure. | Item {.nowrap} | Role {.nowrap} | Notes | | --- | --- | --- | | **Hierarchy** | Dimension | Specified from the top level down (for example: country → state → city). | | **Value** | Metric | If specified, the sum of this becomes the drawing weight. If not specified, aggregation is done by count. | #### Examples * Show "sales breakdown by region → state → city" as a sunburst chart. * **Hierarchy**: region, state, city. * **Value**: sum of sales. * Show "count by organizational hierarchy" as a tree. * **Hierarchy**: division, section, team. * **Value**: none (aggregated by row count). ### Specification by drawing type {#drawing-type-details} * Tree, treemap, and sunburst draw the hierarchical structure as-is. * Bar chart (drill down) starts from the top level, and selecting an item navigates to the next level. * Specify 2 or more levels, and set the drawing type to "Bar chart (drill down)". ## Tips ### Frame {#frame-feature} Hierarchy Chart (tree, treemap, sunburst) supports the frame feature. Bar chart (drill down) doesn't. See [Frame](./common-settings/frame#frame-feature) for details. --- --- url: 'https://docs.codatum.com/features/notebook/chart/graph-chart.md' description: A chart that visualizes relationships or transitions between items --- # Graph Chart Graph Chart visualizes relationships or transitions between items. It aggregates a **weight** (metric) for each combination of **source** and **target** (dimensions). ## Drawing types {#drawing-types} Graph Chart supports the following drawing types. ![Graph Chart](/chart-capture/graph-graph-light.png "Graph"){.light-only .chart-capture} ![Graph Chart](/chart-capture/graph-graph-dark.png "Graph"){.dark-only .chart-capture} ![Sankey Diagram](/chart-capture/graph-sankey-light.png "Sankey"){.light-only .chart-capture} ![Sankey Diagram](/chart-capture/graph-sankey-dark.png "Sankey"){.dark-only .chart-capture} ## Specification ### Aggregation {#aggregation} Graph Chart [aggregates a weight (metric) for each combination of source and target (dimensions)](./concept/dimension-metrics#dimension-metric) and draws the relationships between nodes. | Item {.nowrap} | Role | Notes | | --- | --- | --- | | **Source** | Dimension | The node the connection originates from. | | **Target** | Dimension | The node the connection points to. | | **Weight** | Metric | Reflected in edge thickness or node size. | #### Examples * Show "number of page transitions" as a Sankey diagram. * **Source**: the page transitioned from. * **Target**: the page transitioned to. * **Weight**: sum of transition counts. * Show "mentions between social media users" as a graph. * **Source**: the mentioning user. * **Target**: the mentioned user. * **Weight**: sum of mention counts. ### Specification by drawing type {#drawing-type-details} #### Graph * Turning on **Undirected graph** treats the connection between source and target as bidirectional, merging A→B and B→A into one. * **Link node color to weight** changes node color based on the node's weight. #### Sankey * The direction of flow is drawn visually. * If the data contains a circular reference, the chart can't be drawn, and the message "The data contains a circular reference, so it can't be drawn as a Sankey diagram" is shown. ## Tips ### Frame {#frame-feature} Graph Chart supports the frame feature. See [Frame](./common-settings/frame#frame-feature) for details. --- --- url: 'https://docs.codatum.com/features/notebook/chart/funnel-chart.md' description: A chart that visualizes changes in a step-by-step process --- # Funnel Chart Funnel Chart visualizes changes in a step-by-step process. It aggregates a **value** (metric) for each **label** (dimension) and shows the size or ratio of each step. ![Funnel](/chart-capture/funnel-funnel-light.png "Funnel"){.light-only .chart-capture} ![Funnel](/chart-capture/funnel-funnel-dark.png "Funnel"){.dark-only .chart-capture} ## Specification ### Aggregation {#aggregation} Funnel Chart [aggregates a value (metric) for each label (dimension)](./concept/dimension-metrics#dimension-metric) and shows the result as steps. | Item {.nowrap} | Role | Notes | | --- | --- | --- | | **Label** | Dimension | The name of each funnel step. | | **Value** | Metric | Displayed as the value of each step. | #### Examples * Show the counts of "visit → sign-up → add to cart → purchase" as a funnel. * **Label**: the name of each step. * **Value**: sum of counts. ### Sort order {#sort} The **sort** setting in **basic settings** controls the order. * When the sort type is **Label**, the order isn't changed, and the ratio is calculated based on the first value. * When the sort type is **Value** (ascending or descending), the ratio is calculated based on the maximum value. ## Tips ### Frame {#frame-feature} Funnel Chart supports the frame feature. See [Frame](./common-settings/frame#frame-feature) for details. --- --- url: 'https://docs.codatum.com/features/notebook/chart/waterfall-chart.md' description: A chart that shows the cumulative increase and decrease of items --- # Waterfall Chart Waterfall Chart shows the cumulative increase and decrease of items. The order of **labels** (dimension) determines the stacking order, and the sign of the **value** (metric) represents an increase or decrease. ![Waterfall](/chart-capture/waterfall-waterfall-light.png "Waterfall"){.light-only .chart-capture} ![Waterfall](/chart-capture/waterfall-waterfall-dark.png "Waterfall"){.dark-only .chart-capture} ## Specification ### Aggregation {#aggregation} Waterfall Chart [aggregates a value (metric) for each label (dimension)](./concept/dimension-metrics#dimension-metric) and displays the result cumulatively. | Item {.nowrap} | Role | Notes | | --- | --- | --- | | **Label** | Dimension | The name of each waterfall item. Its order becomes the stacking order. | | **Value** | Metric | Displayed as the increase/decrease value of each item. | You can control the order of labels with **sort**. Since order directly affects the meaning of the visualization, make sure to configure it to reflect the intended order. #### Example * Show the change from "opening balance → revenue → expenses → other" as a waterfall (for example, a breakdown of profit/loss or cash flow). * **Label**: names such as opening, revenue, expenses, other, and closing. * **Value**: the amount (increase/decrease) of each item. ## Tips ### Frame {#frame-feature} Waterfall Chart supports the frame feature. See [Frame](./common-settings/frame#frame-feature) for details. --- --- url: 'https://docs.codatum.com/features/notebook/chart/table-chart.md' description: A table chart showing raw or aggregated data --- # Table Chart Table Chart displays data as a table. The **source type** lets you choose between a raw table that shows fetched rows as-is, and an aggregated table that groups and aggregates data. ## Drawing types {#drawing-types} Table Chart supports the following drawing types. ![Table Raw](/chart-capture/table-raw-light.png "Raw table"){.light-only .chart-capture} ![Table Raw](/chart-capture/table-raw-dark.png "Raw table"){.dark-only .chart-capture} ![Table Aggregated](/chart-capture/table-aggregated-light.png "Aggregated table"){.light-only .chart-capture} ![Table Aggregated](/chart-capture/table-aggregated-dark.png "Aggregated table"){.dark-only .chart-capture} ## Specification ### Source type {#source-type} Table Chart has two source types, and the aggregation and display specification differs depending on which one you select. | Source type {.nowrap} | Description {.nowrap} | Column role | | --- | --- | --- | | Raw data (raw table) | Displays fetched rows as-is. | Select the **columns** to display. | | Aggregated data (aggregated table) | Groups and aggregates data. | [**Group by** (dimension), **Values** (metric)](./concept/dimension-metrics#dimension-metric). | ## Tips ### Image display {#image-preview} If a column's value is an image URL, you can display the image within the table chart by turning on **Enable** in **advanced settings** > **Column settings** > **Image URL preview**. ![Table Image Preview](/chart-capture/table-image-preview-light.png "Image display"){.light-only .chart-capture} ![Table Image Preview](/chart-capture/table-image-preview-dark.png "Image display"){.dark-only .chart-capture} ### Link display {#link-url} If a column's value is a URL, you can show a link in the table chart that opens the URL in a new tab by turning on **advanced settings** > **Column settings** > **Enable link URL**. ![Table Link URL](/chart-capture/table-link-url-light.png "Link display"){.light-only .chart-capture} ![Table Link URL](/chart-capture/table-link-url-dark.png "Link display"){.dark-only .chart-capture} #### Creating a link to a report with parameters {#report-param-link} By dynamically generating a URL with SQL, you can pass each row's data as a parameter to another report page. 1. Create the report and get the URL. * Set a parameter on the destination report, then copy the URL from the browser's address bar. * Example URL: `https://app.codatum.com/workspace/{workspace_id}/report/{report_id}/{page_id}` * Checking the parameter ID: note the ID of the parameter widget in the report (for example: `68f369edf5e6f69036b8872d`). 2. Create a URL column with SQL. * Use the `CONCAT` function to generate a URL that includes each row's data as a parameter, and insert it into the chart. * Example with a single parameter (country name): ```sql CONCAT( 'https://app.codatum.com/workspace/{workspace_id}/report/{report_id}/{page_id}?cdm.params.{parameter_id}=', country -- the column name to pass as the parameter ) AS link ``` 3. Enable the link in the table chart. * Open the target column under **advanced settings** > **Column settings**, and turn on **Enable link URL**. ##### Notes * Replace `country` with the name of the database column you want to pass as the parameter. * The current value of a parameter widget can't be referenced in SQL (only fixed values or column values). * When a user selects a cell, the report opens in a new tab. * For details on setting up parameters, see [Specifying values from a URL](../parameter/url). --- --- url: 'https://docs.codatum.com/features/notebook/chart/pivot-table.md' description: A two-dimensional cross-tabulation table --- # Pivot Table Pivot Table cross-tabulates a **value** (metric) against **rows** and **columns** (dimensions) and displays the result as a two-dimensional table. ![Pivot Table](/chart-capture/pivot-table-light.png "Pivot Table"){.light-only .chart-capture} ![Pivot Table](/chart-capture/pivot-table-dark.png "Pivot Table"){.dark-only .chart-capture} ## Specification ### Field roles {#fields} Pivot Table [treats rows and columns as dimensions and the value as a metric](./concept/dimension-metrics#dimension-metric), and shows the aggregated result as a table. | Item {.nowrap} | Role | Notes | | --- | --- | --- | | **Rows** | Dimension | One or more. | | **Columns** | Dimension | Optional. | | **Value** | Metric | Supports numeric and string metrics. | You can control the order with **row sort** / **column sort**. See [Filter, sort, and limit](./concept/filter-sort-limit#sort) for details. ## Tips ### Drill down {#drill-down} Pivot Table can display rows hierarchically and let you collapse them. Set this up as follows. 1. Set multiple row fields. * In the chart settings, set 2 or more fields for **Rows**, such as a major category and a minor category. * Example: state (major category) → city (minor category). 2. Switch to tree display. * In **advanced settings** > **Layout** > **Default hierarchy type**, choose **Tree**. * Grid: the conventional table format. * Tree: displays a hierarchical structure. You can expand and collapse it using the toggle icon. 3. Set the initial state to collapsed (optional). * Checking **Collapse by default** collapses all levels of the hierarchy on initial display. Additional notes: * This can only be set when there are 2 or more row fields. * Report viewers can freely expand and collapse the hierarchy. ### Differences by processing method {#processing-diff} Pivot Table shows different results depending on whether [in-memory processing](./concept/overview#in-memory-processing) was used or SQL-based processing was used. * With in-memory processing * There's no limit on the number of rows or columns, and all aggregated data can be displayed. * With SQL-based processing * Rows and columns are each limited to a maximum of 30. * If there are more than 30, the excess is grouped into a row or column labeled `(Others)`. * When both rows and columns are specified, the display is limited to roughly 31 × 31 = 961 items due to the rendering cap (1000 rows). The fixed limits are also documented in [Limits](../../../reference/limits#fixed-limits). --- --- url: 'https://docs.codatum.com/features/notebook/chart/text-panel.md' description: A panel that displays the first value of a selected column --- # Text Panel Text Panel displays the first value of a selected column as text. It's useful when you want to show text from a SQL run result, or a dynamic summary on a dashboard together with the [AI agent](../../ai-agent/overview). It doesn't process data (no aggregation by dimensions or metrics). ## Drawing types {#drawing-types} Choose the display format with **rendering mode** in **advanced settings**. ![Text Panel Markdown](/chart-capture/textpanel-markdown-light.png "Markdown"){.light-only .chart-capture} ![Text Panel Markdown](/chart-capture/textpanel-markdown-dark.png "Markdown"){.dark-only .chart-capture} ![Text Panel Raw](/chart-capture/textpanel-raw-light.png "Plain text"){.light-only .chart-capture} ![Text Panel Raw](/chart-capture/textpanel-raw-dark.png "Plain text"){.dark-only .chart-capture} ## Specification ### Aggregation {#aggregation} Text Panel doesn't aggregate data. It displays the first value of the column selected in **Value** under **basic settings**. If the value is NULL, nothing is displayed. ### Specification by drawing type {#drawing-type-details} **Rendering mode** in **advanced settings** offers the following choices. * **Markdown**: renders the output text as markdown. * **Plain text**: displays the output text as-is. --- --- url: 'https://docs.codatum.com/features/notebook/chart/map-chart.md' description: >- A chart that displays data on a map using latitude/longitude, geohash, geocode, or GeoJSON --- # Map Chart Map Chart displays data on a map. You can specify locations using latitude/longitude, geohash, geocode, or GeoJSON. The available drawing types depend on the data format. ## Data formats {#data-formats} Map Chart can display the following data formats on a map. ### Latitude/longitude {#lat-lng} Draws objects at the specified latitude/longitude position. Specify numeric columns for latitude and longitude. Available with the following drawing types. ![Map Pin](/chart-capture/map-pin-light.png "Pin"){.light-only .chart-capture} ![Map Pin](/chart-capture/map-pin-dark.png "Pin"){.dark-only .chart-capture} ![Map Bubble](/chart-capture/map-bubble-light.png "Bubble"){.light-only .chart-capture} ![Map Bubble](/chart-capture/map-bubble-dark.png "Bubble"){.dark-only .chart-capture} ![Map Heatmap](/chart-capture/map-heatmap-light.png "Heatmap"){.light-only .chart-capture} ![Map Heatmap](/chart-capture/map-heatmap-dark.png "Heatmap"){.dark-only .chart-capture} ![Map Flow](/chart-capture/map-flow-light.png "Flow"){.light-only .chart-capture} ![Map Flow](/chart-capture/map-flow-dark.png "Flow"){.dark-only .chart-capture} \* Flow requires two sets (source and target) of latitude/longitude. ### Geohash {#geohash} Draws objects at the position specified in [geohash](https://en.wikipedia.org/wiki/Geohash) format. The following drawing types (same as latitude/longitude) draw an object at the center point of the specified geohash. * Pin * Bubble * Heatmap * Flow The following drawing type fills in the area of the specified geohash. (The size of the filled area varies depending on the precision of the geohash.) ![Map Mesh](/chart-capture/map-mesh-light.png "Mesh"){.light-only .chart-capture} ![Map Mesh](/chart-capture/map-mesh-dark.png "Mesh"){.dark-only .chart-capture} #### Geohash samples Here are sample geohashes. | Geohash {.nowrap} | Precision | Example location | Approximate area size | | --- | --- | --- | --- | | xn | 2 characters | Around Tokyo | 630km × 500km | | xn7 | 3 characters | Central Tokyo | 78km × 78km | | xn76 | 4 characters | Tokyo Station area | 20km × 10km | | xn76u | 5 characters | Around Tokyo Station | 2.4km × 2.4km | | xn76ur | 6 characters | Near Tokyo Station | 610m × 300m | | xn76urx | 7 characters | Close to Tokyo Station | 76m × 76m | | xn76urxk | 8 characters | Around Tokyo Station | 19m × 9m | #### BigQuery example In BigQuery, you can use the `ST_GEOHASH` function to convert latitude/longitude data to a geohash. Converting to a geohash allows more efficient area-based aggregation and grouping than handling latitude/longitude individually. The following example uses BigQuery's `ST_GEOHASH` function to convert latitude/longitude data to a geohash. ```sql SELECT ST_GEOHASH(ST_GEOGPOINT(longitude, latitude), 6) AS geohash, COUNT(*) AS station_count FROM `bigquery-public-data.new_york_citibike.citibike_stations` GROUP BY geohash ORDER BY station_count DESC ``` ### Geocode {#geocode} Fills in the area associated with a geocode. Available with the following drawing type. ![Map Area](/chart-capture/map-area-light.png "Area"){.light-only .chart-capture} ![Map Area](/chart-capture/map-area-dark.png "Area"){.dark-only .chart-capture} Specify a geocode using a string in one of the following formats. | Granularity {.nowrap} | Geocode format | Geocode example | | --- | --- | --- | | Country | 2-letter country code ([ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1), uppercase) | JP | | Prefecture (Japan only) | `"JP-"` + 2-digit prefecture code ([JIS X 0402](https://en.wikipedia.org/wiki/JIS_X_0402)) | JP-13 | | Municipality (Japan only) | `"JP-"` + 5-digit municipality code ([JIS X 0402](https://en.wikipedia.org/wiki/JIS_X_0402)) | JP-13101 | | First 2 digits of postal code (Japan only) | `"JP-POST-"` + first 2 digits of postal code | JP-POST-10 | | First 3 digits of postal code (Japan only) | `"JP-POST-"` + first 3 digits of postal code | JP-POST-100 | The geospatial data used to fill areas is a lightweight, processed version of the following sources. * Global country boundary data: [Natural Earth](https://www.naturalearthdata.com/) * Boundary data within Japan: ["National Land Numerical Information (Administrative Areas)" (Ministry of Land, Infrastructure, Transport and Tourism)](https://nlftp.mlit.go.jp/ksj/gml/datalist/KsjTmplt-N03-2025.html) * Postal code boundary data: [郵便番号境界データ（地図地理Sandbox）](https://hanishina.net/maps/yubindata.html) A geocode that's valid in format but not included in the above data can't be drawn. #### Geocode samples Here are sample geocodes. See the [CSV file of available geocodes](https://static.codatum.com/v/latest/public/geojson/codes.csv) for the full list of available geocodes. | Geocode {.nowrap} | Name | | --- | --- | | US | United States | | JP | Japan | | JP-01 | Hokkaido | | JP-02 | Aomori Prefecture | | JP-03 | Iwate Prefecture | | JP-01100 | Sapporo City | | JP-01101 | Sapporo, Chuo Ward | | JP-01102 | Sapporo, Kita Ward | | JP-01103 | Sapporo, Higashi Ward | | JP-01202 | Hakodate City | | JP-01203 | Otaru City | | JP-01204 | Asahikawa City | | JP-POST-10 | Postal codes 10X-XXXX | | JP-POST-100 | Postal codes 100-XXXX | ### GeoJSON {#geojson} Draws geometry data specified in GeoJSON format on a map. Available with the following drawing types. ![Map Polygon](/chart-capture/map-polygon-light.png "Polygon"){.light-only .chart-capture} ![Map Polygon](/chart-capture/map-polygon-dark.png "Polygon"){.dark-only .chart-capture} ![Map Polyline](/chart-capture/map-polyline-light.png "Polyline"){.light-only .chart-capture} ![Map Polyline](/chart-capture/map-polyline-dark.png "Polyline"){.dark-only .chart-capture} Specify JSON of the following geometry types as a string column. * `Point` * `LineString` * `Polygon` * `MultiPoint` * `MultiLineString` * `MultiPolygon` * `GeometryCollection` #### GeoJSON sample ```json { "type": "Polygon", "coordinates": [ [ [-73.9812, 40.7681], [-73.9581, 40.7681], [-73.9581, 40.8007], [-73.9812, 40.8007], [-73.9812, 40.7681] ] ] } ``` #### BigQuery example In BigQuery, you can use the `ST_ASGEOJSON` function to convert geometry data to GeoJSON format. The following example converts the `county_geom` column of the `bigquery-public-data.geo_us_boundaries.counties` table to GeoJSON format. ```sql SELECT * EXCEPT (county_geom), ST_ASGEOJSON(county_geom) AS county_geom FROM `bigquery-public-data.geo_us_boundaries.counties` WHERE state_fips_code = '36' -- New York ``` If the size of the geometry data you want to draw is large, it might hit the size limit for SQL run results and cause an error. In that case, you can use the `ST_SIMPLIFY` function to simplify the geometry data and reduce its size. Large geometry data also affects rendering performance, so simplify it to the minimum size necessary. ```sql SELECT * EXCEPT (county_geom), ST_ASGEOJSON(ST_SIMPLIFY(county_geom, 1000)) AS county_geom FROM `bigquery-public-data.geo_us_boundaries.counties` WHERE state_fips_code = '36' -- New York ``` ## Usage limitations {#limitations} Map Chart uses WebGL to render maps, which brings the following limitations. * It can't be drawn in browsers that don't support WebGL. * Because of limits on the number of WebGL contexts, trying to render many map charts at the same time might discard charts that were rendered earlier. * Redrawing restores the display, but be careful not to have too many map charts on a single page. --- --- url: 'https://docs.codatum.com/features/notebook/chart/word-cloud.md' description: A chart that visually shows the frequency or importance of keywords --- # Word Cloud Word Cloud aggregates a **value** (metric) for each **word** (dimension) and visualizes the weight of each word using font size and other visual cues. ![Word Cloud](/chart-capture/word-cloud-light.png "Word Cloud"){.light-only .chart-capture} ![Word Cloud](/chart-capture/word-cloud-dark.png "Word Cloud"){.dark-only .chart-capture} ## Specification ### Aggregation {#aggregation} Word Cloud [aggregates a value (metric) for each word (dimension)](./concept/dimension-metrics#dimension-metric) and displays the result. | Item {.nowrap} | Role | Notes | | --- | --- | --- | | **Word** | Dimension | Each word in the word cloud. | | **Value** | Metric | Determines the size of the word. | #### Example * Show content tags as a word cloud. * **Word**: tag name. * **Value**: number of pieces of content with that tag. ## Tips ### If some words don't appear {#missing-words} Word Cloud draws words in descending order of value, and words that don't fit in the display area are automatically hidden. As a result, words with small values might not be displayed. If you have many words and not all of them are shown, adjust **advanced settings** > **Word settings** > **font size range**, **word spacing**, or the chart's display area. Enabling **Automatically shrink words** lets font sizes automatically adjust for words that don't fit in the display area. However, with a large number of words, recalculating font sizes can make the chart feel slow. Because of this, the feature is disabled by default. Be mindful of the word count when enabling it. ### Frame {#frame-feature} Word Cloud supports the frame feature. See [Frame](./common-settings/frame#frame-feature) for details. --- --- url: 'https://docs.codatum.com/features/notebook/explorer.md' description: >- A feature for filtering, aggregating, and pivoting run results without writing SQL, and connecting the results to charts or SQL blocks --- # Explorer Explorer lets you explore SQL run results, chart data sources, and table preview data through a GUI. You can analyze data with filtering, sorting, aggregation, and pivoting without writing SQL, and even add charts or SQL blocks to the notebook from the results. ## Key features | Feature {.nowrap} | Description | | --- | --- | | [Switching views](#views) | Switch the exploration approach between **Raw data**, **Aggregated data**, and **Pivot**. | | [Setting conditions](#conditions) | Specify **Filter**, **Sort**, **Limit**, and more through a GUI. | | [Result tabs](#result-tabs) | Switch between **Processed data**, **Distribution**, **Chart**, **SQL**, and **Source data**. | | [Column header operations](#column-menu) | Add sorting, filters, or column statistics from a table's column. | | [Using exploration results](#use-results) | Add a chart or SQL block, or download data. | ## Opening Explorer {#open} You can open Explorer in any of the following ways. ### Doc page * Once a [SQL block](./doc-page/sql-block) has run successfully, select **Explorer** in the run result header. * Select **Explorer** from the float menu of a [chart](./chart/overview). * Select **Explorer** on a **Table preview** block. * From the icon on a value cell in [column stats](./doc-page/sql-block#column-stats), select **Open explorer**. ### Grid page * From the menu of a **Query result** or **Chart** on a [grid page](./grid-page/overview), select **Explorer**. When opened from a grid page, you can't add a chart or SQL block. Only exploration and downloading (if allowed) are available. ## Layout {#layout} Explorer opens as a full-screen view, divided mainly into the following areas. | Area {.nowrap} | Content | | --- | --- | | Header | Title, **auto-run toggle**, adding a chart or SQL block, **Download**. | | Left pane | **Data source** (column list) and the condition form. | | Right pane | [Result tabs](#result-tabs). | ## Exploring data {#explore} 1. At the top of the condition form in the left pane, choose **Raw data**, **Aggregated data**, or **Pivot**. 2. Drag and drop columns from **Data source**, or add fields using each item's selector. Use **Filter columns** to narrow the list. You can toggle the display between **By data type** and **In original order**. 3. Set **Filter**, **Sort**, and **Limit** in [common conditions](#conditions). 4. If the right pane shows `Conditions changed. Please re-run the query.`, select **Run query**, or turn on **Auto-run** in the header. 5. Review the results in the tabs of the right pane. Turning on **Auto-run** re-runs SQL automatically whenever conditions change, for as long as Explorer stays open. It turns off again when you close Explorer. ## Using exploration results {#use-results} When opened from a doc page and you have edit permission on the notebook, you can do the following. | Operation {.nowrap} | Description | | --- | --- | | **Add chart** | Adds a chart suggested from the current exploration conditions, and closes Explorer. | | **Add chart and continue** | Adds the chart while keeping Explorer open. | | **Edit in chart editor** | Opens the chart editor, and closes Explorer. | | **Add SQL block** | Creates a new SQL block with SQL equivalent to the current conditions, and closes Explorer. | | **Add SQL block and continue** | Adds the SQL block while keeping Explorer open. | | **Download** | Downloads data based on the current Explorer conditions. | Adding a chart is available when Explorer was opened from a SQL block's run result (or a chart under it). When opened from a table preview, select **Add SQL block** first, then add the chart. ## Views {#views} Field settings carry over as much as possible when you switch views in the condition form. Details for each view are as follows. ### Raw data Explores unaggregated raw data. | Item {.nowrap} | Description | | --- | --- | | **Target data** > **Columns** | Specifies the columns to display. | | **Common conditions** | **Filter** / **Sort** / **Limit**. | ### Aggregated data Explores data grouped and aggregated by selected columns. | Item {.nowrap} | Description | | --- | --- | | **Aggregation conditions** > **Group by** | Specifies the columns to group by (equivalent to a chart's dimensions). | | **Aggregation conditions** > **Values** | Specifies the columns to aggregate and the **aggregation method** (equivalent to a chart's metrics). | | **Common conditions** | **Filter** / **Sort** / **Limit**. | Either **Group by** or **Values** is required. See [Dimensions and metrics](./chart/concept/dimension-metrics#aggregation) for details on **aggregation method**. ### Pivot Explores data aggregated across two dimensions: rows and columns. | Item {.nowrap} | Description | | --- | --- | | **Pivot conditions** > **Rows** | Specifies the columns to use as the row axis. | | **Pivot conditions** > **Columns** | Specifies the columns to use as the column axis. | | **Pivot conditions** > **Values** | Specifies the aggregated values shown in each cell. Required. | | **Pivot conditions** > **Row sort** / **Column sort** | Specifies the order of each axis. Defaults to descending order of the value. | | **Common conditions** | **Filter** (no **Sort** or **Limit**). | ## Common conditions and options {#conditions} ### Filter **Filter** narrows down data by combining a column, an operator, and a value. Operators and the handling of **Custom SQL** are the same as a chart's [source filter](./chart/concept/filter-sort-limit#source-filter). **Custom SQL** isn't available for snapshot sharing (such as reports). ### Sort **Raw data** and **Aggregated data** let you specify **Sort**. You can sort by multiple columns. ### Limit **Raw data** and **Aggregated data** let you specify **Limit** between 1 and 1000. See [Limits](../../reference/limits#fixed-limits) for the upper bound. ### Disabling in-memory processing {#in-memory-processing} Turning on **Options** > **Disable in-memory processing** re-runs SQL according to the current conditions instead of processing already-fetched data. By default, if the result has 1000 rows or fewer and there's no **Custom SQL**, filtering and aggregation can be done through in-memory processing in the browser. If the source data has more than 1000 rows and has been truncated, SQL needs to be re-run. See [Chart concepts](./chart/concept/overview#in-memory-processing) for how this relates to the same option on charts. ## Result tabs {#result-tabs} | Tab {.nowrap} | Description | | --- | --- | | **Data** / **Processed data** | Shows a table as **Data** when no conditions are set, or **Processed data** once conditions are set. In the pivot view, this is a pivot table. | | **Distribution** | Choose **Parallel** or **Scatter plot matrix** as the **display method**, and check the distribution of up to 5 **target columns**. Requires 2 or more columns. | | **Chart** | Switch between suggested chart candidates for the current conditions using **chart type**, and preview the appearance after adjusting quick settings. | | **SQL** | Shows the processing SQL issued based on the current conditions. | | **Source data** | Shows the source data before processing. | ## Column header operations {#column-menu} Hovering over a column header in the **Processed data** table gives you the following operations. | Operation {.nowrap} | Description | | --- | --- | | **Sort** | Sorts by **ascending** or **descending** order. Use **Add** to add to existing sort conditions. | | **Filter by value** | Adds an `IN` condition by selecting from candidate values. If a value isn't in the list, use **Fetch unsampled values** to expand the candidates, then select **Apply**. | | **Exclude by value** | Adds a `NOT IN` condition by selecting from candidate values. | | **Filter by condition** | Adds a condition such as **Equal to**, **Not equal to**, **Between**, or **Greater than**. | | **NULL filter** | Adds `IS NULL` or `IS NOT NULL`. | | **Column stats** | Select **Get column stats** to check the count, unique count, number of NULL values, max / min / average, and more. | ## Where you can use it {#availability} | Location {.nowrap} | Availability | | --- | --- | | Notebook (doc page / grid page) | Available. Add operations are limited to editing a doc page. | | [Report](./sharing/report/overview) | Available for **interactive reports** with **Enable explorer** turned on in the publish settings. Disabled by default. | | [Signed embed](./sharing/signed-embed/overview) | Available when **Enable explorer** is turned on in the publish options. Disabled by default. | | [Public link](./sharing/public-link/overview) | Not available. | See [Sharing](./sharing/overview#comparison) for a comparison of notebook sharing methods. --- --- url: 'https://docs.codatum.com/features/notebook/comment.md' description: Collaboration through comments and mentions on notebooks and reports --- # Comment Comments let you attach discussion or feedback to a range in the body of a notebook or report. You can also use `@` [mentions](#mention) in the body or in comments. See [Notification preferences](../../account/settings/notification) for notification settings. Whether you can comment follows the view permission of the target resource ([notebook permissions](../../permissions/resources/notebook), [report permissions](../../permissions/resources/report)). While a notebook is [locked](./overview#lock), you can't edit it, but you can still comment. ## Key features * [Adding a comment](#add-comment): create a thread on a selected range of the body * [Comment list](#comment-list): list and filter from **Comments** in [the right sidebar](../../guide/screen-layout) * [Mentions](#mention): mention a user in the body or in comments * [Comments in reports](#report-comments): availability and disabling in the report view ## Adding a comment {#add-comment} Prerequisite: you need view permission on the target notebook or report. 1. Select the text or block range in the body that you want to comment on. 2. From the menu that appears, select **Add comment**. 3. Enter your comment and select **Add**. A marker appears where existing comments are attached. Select **Open comment** to open the thread. For each comment, you can do the following. * **Edit** / **Delete** (your own comments) * **Add reaction** * **Resolve** * **Copy link** (link to the thread) ## Comment list {#comment-list} Open **Comments** in [the right sidebar](../../guide/screen-layout) to see a list of comments on the current page. In reports, you can also open this from **Comments** in the header. The list can be filtered as follows. | View {.nowrap} | Description | | --- | --- | | **Open** | Active comments and comments with broken references. | | **Active** | Unresolved comments whose target range is still valid. | | **Broken reference** | Comments whose target range can no longer be referenced, for example because it was deleted. | | **Resolved** | Comments closed with **Resolve**. | ## Mentions {#mention} While typing in the body or in a comment, type `@` to choose a workspace user from a list of candidates. Mentioned users receive a notification according to their [notification preferences](../../account/settings/notification). | Location {.nowrap} | Notification event (notebook) | | --- | --- | | Notebook body | **Mention in notebook** | | Notebook comment | **Mention in comment** / **Reply in comment** | For comments on reports, the targets are **Mention in comment** / **Reply in comment**. ## Comments in reports {#report-comments} You can comment on reports the same way as on notebooks. If **Disable comments** is turned on in the report settings, comments are unavailable for that report (see [Report settings](./sharing/report/overview#report-settings)). It's off (comments available) by default. Comments aren't available in signed embeds. --- --- url: 'https://docs.codatum.com/features/notebook/version.md' description: Automatic and manual notebook versions --- # Version Version lets you save, restore, and compare the analysis state of a notebook. Select **Version** from the menu on the right side of [the header](../../guide/screen-layout) in the notebook screen to show it in the right sidebar. Parameter values and run results within a version are specific to each user and aren't synced to other users. Parameter changes can also be synced to the URL (see [Specifying values from a URL](./parameter/url)). ## Kinds of versions {#kinds} | Kind {.nowrap} | Description | | --- | --- | | **Manual** | Created manually by a user. Never overwritten automatically. | | **Automatic** | Created automatically when changes are made. Not created more often than roughly once per hour. Older automatic versions are deleted. | | **Published** | Created when publishing a report, signed embed, or similar. | | **AI edit** | Created automatically before edits made by, for example, Agent mode in the [AI agent](../ai-agent/overview#operation-modes) (used for rollback). | ## Operations {#operations} From a version's menu, you can do the following. | Operation {.nowrap} | Description | | --- | --- | | **Restore this version** | Restores the current notebook to the content of the selected version. Requires edit permission on the notebook. | | **Create new from version** | Creates a new notebook from the selected version. | | **Compare with current notebook** | Compares the selected version with the current notebook. | | **Copy URL** | Copies the URL of a manual version. | | **Delete** | Deletes a manual version. | --- --- url: 'https://docs.codatum.com/features/notebook/export.md' description: Exporting notebooks and importing selected pages --- # Export and import You can export the content of a notebook as a file, and use an exported file to restore pages or create a new notebook. Exported files can be used as backups or with the [Codatum CLI](../cli/overview). ## Export From the menu in [the header](../../guide/screen-layout) inside a notebook, select **Export** to export in the following formats. | Menu | Format | Description | | --- | --- | --- | | **Export** | `.yml` | Exports the entire notebook as a file. Use this file for the import steps below. | | **Export as Markdown file** | `.cnb.md` | A notebook file format usable with the Codatum CLI (available in workspaces where the Codatum CLI is enabled). | | **Export as SQL files** | `.zip` | Exports SQL blocks as `.sql` files. See the `README.md` in the output for details. | | **Export as dbt project** | `.zip` | Exports SQL blocks as a dbt project. See the `README.md` in the output for details. | ## Import {#import} Import an exported `.yml` file into either of the following destinations. * **Import as a new notebook** * **Add pages to the open notebook** In both cases, after you select the file, choose the pages to import under **Target pages**. All pages are selected by default. Clear the pages you don't need, then select **Import**. ### Import as a new notebook {#import-as-new} 1. In the folder tree in [the left sidebar](../../guide/screen-layout) of the notebook list, open **Add notebook or folder**. 2. Select **Import from file**. 3. Select **Select file** and choose the `.yml` file. 4. Under **Target pages**, select the pages to import. 5. Check the [Fallback connection](#fallback-connection), then select **Import**. A new notebook is created that contains only the selected pages. ### Add pages to an existing notebook {#import-pages} 1. Open the destination notebook. 2. From the menu in [the header](../../guide/screen-layout), select **Import pages**. 3. Select **Select file** and choose the `.yml` file. 4. Under **Target pages**, select the pages to add. 5. Check the [Fallback connection](#fallback-connection), then select **Import**. The selected pages are appended to the open notebook. ### Fallback connection {#fallback-connection} This is the replacement connection used when a connection specified in the notebook isn't available. If you enable **Force replace all**, every connection is replaced with the fallback connection, regardless of availability. ::: tip You can still export a notebook that has become uneditable because it exceeds the size limit. Import only the pages you need into a new notebook to keep editing. ::: --- --- url: 'https://docs.codatum.com/features/notebook/folder.md' description: Notebook placement and access scope --- # Folder Notebooks are organized into folders. The **root folder** a notebook belongs to determines its [access scope](../../permissions/resources/notebook#access-scope). Moving a notebook across root folders also changes its access scope. In the folder tree in [the left sidebar](../../guide/screen-layout) of the notebook list, folders are shown under the following headings. | Heading {.nowrap} | Root folder name {.nowrap} | Permissions | | --- | --- | --- | | All members | Workspace | Access depends on the workspace role. | | Teamspaces | (each teamspace name) | Access depends on the resource role in the [teamspace](../../workspace/administration/teamspace). | | Direct shared | Shared | Accessible to users and groups granted [additional notebook permissions](./sharing/additional-permissions/overview). | | Personal | Private | Only the owner, if also a [workspace editor](../../workspace/administration/user#workspace-roles) or above, can operate on it. | The root folders shown also depend on the user's permissions. Depending on your contract, teamspace, shared, and private folders might not be available. See [Notebook permissions](../../permissions/resources/notebook#access-scope) for the conditions for each operation. ## Creating and managing {#manage} In the folder tree in [the left sidebar](../../guide/screen-layout), open **Add notebook or folder** to do the following. * **New notebook** * **Create from template** (see [Creating from a template](./overview#templates)) * **Import from file** (see [Export and import](./export)) * **New folder** From a folder's menu, you can **Rename folder**, **Move**, or **Delete**. You can also move or delete notebooks in bulk from the notebook list. --- --- url: 'https://docs.codatum.com/features/notebook/sharing/overview.md' description: 'Ways to share a notebook (permissions, report, public link, signed embed)' --- # Sharing This page summarizes the ways to share a notebook's content with other users or externally. You can access these from **Share** on the notebook screen. There's sharing through granting permissions, and sharing through snapshots (report / public link / signed embed). See [Notebook permissions](../../../permissions/resources/notebook) for details on permissions. ## Key features * Granting permissions: basic permissions based on the folder (workspace / teamspace / private), plus [additional notebook permissions](./additional-permissions/overview) * [Report](./report/overview): publish a notebook as a snapshot. For guest invitations, see [Invitations and joining](../../../workspace/administration/invite#guest-invite-from-report) * [Public link](./public-link/overview): a public link and embed that don't require login * [Signed embed](./signed-embed/overview): embedding in an external app using an API key ## Comparing sharing methods {#comparison} | Method {.nowrap} | Scope of operation | Authentication / permissions {.nowrap} | | --- | --- | --- | | Granting permissions | Editing, running SQL, parameters, Explorer | Login required; connection permission also required | | Report | Viewing; running SQL, parameters, and Explorer depend on publish settings | Login required; connection permission not required | | Public link | View only | Login not required | | Signed embed | Viewing; running SQL, parameters, and Explorer depend on settings | Login not required; authenticated with an API key and token | With snapshot sharing (report / public link / signed embed), changes to the notebook itself aren't automatically reflected. You need to select **Publish changes** to reflect them. --- --- url: >- https://docs.codatum.com/features/notebook/sharing/additional-permissions/overview.md description: >- Add permissions for teamspace and private notebooks to specific users or groups --- # Additional notebook permissions (Optional feature) Additional notebook permissions let you grant access to a notebook to specific users or groups, separately from the basic permissions determined by [folder](../../folder). See [Sharing](../overview#comparison) for a comparison of sharing methods. You can configure this for notebooks under the following folders. * [Teamspace](../../../../workspace/administration/teamspace) * Private You can't configure this for notebooks under the **Workspace** folder. A notebook granted additional permissions is shown in the other party's **Shared folder**. See [Notebook](../../../../permissions/resources/notebook#scope-shared) for the conditions for each operation. ::: tip This is an **optional feature**. Depending on your contract, it might not be available. ::: ## Configuring {#configure} Configuring additional permissions requires share permission on the notebook (the "sharing with users or groups" permission in [Notebook](../../../../permissions/resources/notebook)). 1. Open **Share** on the notebook screen. 2. Open **Additional notebook permissions** in the **Notebook** tab. 3. Select **Add group or member**, then choose a user or group and specify a role. You can grant the following roles. The default is **Notebook viewer**. | Role {.nowrap} | Description | | --- | --- | | **Notebook editor** | Can edit the notebook. | | **Notebook viewer** | Can view the notebook. | You can also change or remove a role from the same screen. You can't edit additional permissions when opening a notebook from the **Shared folder** side. ## Specification {#spec} * The workspace role and the notebook role are evaluated with AND. Even if you grant **Notebook editor**, the recipient can't edit if their workspace role is workspace viewer (see [Permission evaluation rules](../../../../permissions/overview#evaluation-rules)). * A notebook that's only accessible through additional permissions can't be deleted or moved, even with edit permission (see [Notebook](../../../../permissions/resources/notebook#scope-shared)). * Whether SQL can be run is determined by permissions on the target [connection](../../../../permissions/resources/connection), not by notebook permissions. * Moving a notebook between workspace / teamspace / private changes the scope of its basic permissions (see [Folder](../../folder)). * A [workspace owner](../../../../workspace/administration/user#workspace-roles) can view the change history of additional permissions from **History** (see [Audit logs](../../../../workspace/access-and-security/audit-log)). --- --- url: 'https://docs.codatum.com/features/notebook/sharing/report/overview.md' description: Publishing a notebook as a report and sharing it with members and guests --- # Report (Optional feature) A report publishes the content of a notebook as a snapshot at the time it's published. You can share analysis results even with [members and guests](../../../../workspace/administration/user#member-and-guest) who don't have connection permissions. Viewing a report requires logging in to Codatum. Granting permissions and inviting guests after publishing is done from the report side. See [Invitations and joining](../../../../workspace/administration/invite#guest-invite-from-report) for guest invitations, and [Report permissions](../../../../permissions/resources/report) for details on permissions. See [Sharing](../overview#comparison) for a comparison of sharing methods, and [Comment](../../comment#report-comments) for comments. ::: tip This is an **optional feature**. Depending on your contract, it might not be available. ::: ## List {#list} Open [global nav](../../../../guide/screen-layout) > **Reports** to view reports you have access to. You can filter using the following tabs in the left sidebar. | Tab {.nowrap} | Description | | --- | --- | | **All reports** | A list of the reports you can view. | | **Recently viewed** | Reports you've recently opened. | | **Newly added** | Reports that were recently published. | | **Published by me** | Reports you've published. | | **Starred** | Reports you've starred. | You can also filter by tag. Use **Manage tags** to go to the [tag](../../../../workspace/data-management/tag#tag-definition) management screen. ## Publishing {#publish} Publishing requires publish permission on the source notebook, and publish permission on the connections used by the pages being published. Notebooks accessed through a shared folder can't be published. See [Report permissions](../../../../permissions/resources/report) for details on permissions. 1. Open **Share** on the notebook screen, then select the **Report** tab. 2. Select **Create report**. 3. Configure the following, then select **Publish**. | Item {.nowrap} | Description | | --- | --- | | **Report name** | The name of the report. Defaults to the notebook name. You can also set an icon. | | **Pages to publish** | The pages to publish. At least one page other than a **section divider** is required. Defaults to all pages. | | **Embedded connections** | Automatically extracted from the pages being published. Publish permission on the target connections is required. | | **Report type** | Determines the range of operations available to viewers. Defaults to **Interactive report**. | | Publish options | Available options depend on the report type. | After publishing, you can do the following from the **Published reports** list. * Select the name to open the report. * **Publish changes**: republishes to reflect changes to the notebook. You can check the diff with **Compare notebook** before publishing. * **Report settings**: go to the report screen's settings, permissions, and invitations. * **Compare with current notebook** * **Delete** Changes to the notebook itself aren't automatically reflected. You need **Publish changes** to reflect them. Republishing is also required to change the report type, or to change a publish option that requires republishing. ## Publish settings {#publish-settings} You choose the report type and options when publishing. These publish settings determine the range of operations available to report viewers. If you change the report type, or change a publish-time option that requires republishing, you need to select **Publish changes** again. ### Report types {#report-types} | Type {.nowrap} | Description | | --- | --- | | **Interactive report** | Viewers can edit parameters and re-run SQL. | | **Refreshable report** | Viewers can only re-run SQL. | | **Static report** | Shows a fixed display of the run results at the time of publishing. SQL can't be re-run. | ### Publish options {#publish-options} The following options aren't available for a **static report**. | Option {.nowrap} | Description | Applies to | | --- | --- | --- | | **Enable downloads** | Lets report viewers download the source data. | Interactive report | | **Enable Explorer** | Lets report viewers explore the source data. | Interactive report | | **Use fixed parameters** | Fixes some parameters within the report. When enabled, **Embed data at publish time** can't be used, and **Enable auto-run** is turned on. | Interactive report / Refreshable report | | **Embed data at publish time** | Publishes with the SQL run results at the time of publishing embedded. | Interactive report / Refreshable report | | **Enable auto-run** | Automatically runs SQL when the page loads. Turned on automatically if data isn't embedded. Can be changed after publishing from [Report settings](#report-settings) without republishing. | Interactive report / Refreshable report | | **Use parameter default values** | Uses parameter default values on auto-run. Dynamic default values, such as relative dates, are also recalculated. If there are fixed parameters, the fixed values take priority. Can be changed after publishing from [Report settings](#report-settings) without republishing. | Interactive report (when auto-run is enabled) | Permissions and invitations are configured on the report side after publishing. ## Report settings {#report-settings} From **Report settings** on the report screen, you can change the following settings without republishing. Changing them requires publish permission on the source notebook. **Auto-run** and **Use parameter default values** are the same items as the publish options. | Setting {.nowrap} | Description | | --- | --- | | **Report name** / **Tags** | The report's display name and [report tags](../../../../workspace/data-management/tag#tag-types). | | **Auto-run** | Automatically runs SQL when the page loads. Always on if data isn't embedded at publish time. | | **Use parameter default values** | Uses parameter default values on auto-run (interactive report). See [Relative dates](../../parameter/relative-date) for how relative dates are handled. | | **Sync parameter changes across pages** | Syncs changes to notebook-wide parameter values across published pages (interactive report). See [Parameter](../../parameter/overview#report-page-sync) for details. | | **Cache duration** | The maximum period SQL run results can be reused. 0 disables caching; the maximum is 24 hours, in 10-minute increments. | | **Hide SQL block** | Hides SQL blocks and built SQL. | | **Show only results within SQL block** | Hides the SQL portion and built SQL within a SQL block. Can't be set if **Hide SQL block** is enabled. | | **Disable comments** | Disables comments. See [Comment](../../comment#report-comments) for details. | **Publish settings** on the same screen shows the report type and publish options. To change them, go to the sharing screen from **Edit** and republish. ## Permissions and invitations {#permissions} Open **Share report** from **Share** on the report screen to configure the following. * **Users with access**: grant or remove Report Viewer for a user or group. * **Invite guest by email**: invite a user who hasn't joined the workspace as a guest. You can check or cancel pending invitations from **Pending guest invitations**. See [Report permissions](../../../../permissions/resources/report) and [Invitations and joining](../../../../workspace/administration/invite#guest-invite-from-report) for details. ## Report analytics {#analytics} Open **Report analytics** in the report screen's header to check viewing activity. You can choose from the following periods (default is **Last 7 days**). | Period {.nowrap} | Description | | --- | --- | | **Last 7 days** | The most recent 7 days. | | **Last 30 days** | The most recent 30 days. | | **All time** | The entire period since publishing. | The following metrics are shown. | Metric {.nowrap} | Description | | --- | --- | | **Total views** | The number of views within the period. | | **Unique users** | The number of users who viewed it within the period. | | **Average view duration** | The average view duration within the period. | In the user list, you can check **Name** / **First access** / **Last access**. ## Specification {#spec} * Re-running SQL, downloads, and the Explorer within a report don't require connection permission. A report viewer can run them if allowed by the publish settings. * The number you can create has a limit that depends on your contract (see [Limits](../../../../reference/limits#plan-limits)). * A [workspace policy](../../../../workspace/access-and-security/policy#policy-settings) can disable guest invitations by [workspace editors](../../../../workspace/administration/user#workspace-roles). ## When you can't publish {#cannot-publish} Check the following. 1. Whether you have publish permission on the source notebook (notebooks accessed through a shared folder can't be published). 2. Whether you have publish permission on the connections used by the pages being published. 3. Whether you've reached the limit on the number of reports (global nav > **Workspace settings** > **Usage**). --- --- url: 'https://docs.codatum.com/features/notebook/sharing/public-link/overview.md' description: >- Creating, sharing, and managing public links that publish a notebook without requiring login --- # Public link A public link publishes the content of a notebook as a snapshot at the time it's published. Anyone who knows the link can view it without logging in to Codatum. Besides the whole notebook, you can also share URLs for an individual page or an individual chart. Viewers can't do the following. * Change parameters * Re-run SQL * Download * Use the Explorer * Comment See [Sharing](../overview#comparison) for a comparison of sharing methods. ## Creating and managing {#create} Publishing requires publish permission on the source notebook, and publish permission on the connections used by the pages being published. Notebooks accessed through a shared folder can't be published. See [Notebook](../../../../permissions/resources/notebook) and [Connection](../../../../permissions/resources/connection) for details on permissions. 1. Open **Share** on the notebook screen, then select the **Public link** tab. 2. Select **Create public link**. 3. Configure the following, then select **Publish**. | Item {.nowrap} | Description | | --- | --- | | **Link name** | The name of the link. Defaults to the notebook name. You can also set an icon. | | **Published pages** | The pages to publish. At least one page other than a **section divider** is required. | | **Embedded connections** | Automatically extracted from the pages being published. Publish permission on the target connections is required. | | **Enable expiration** | When enabled, published content is deleted after the specified number of days. Disabled by default. When enabled, the default number of days is 30, and you can specify a range from 1 to 90. | After publishing, you can do the following from the **Published public links** list. * Select the name to view it (not a link if it has expired). * **Publish changes**: republishes to reflect changes to the notebook. You can check the diff with **Compare notebook** before publishing. * **Share**: copy the URL after configuring the display options. * **Compare with current notebook** * **Delete** * **Change logs** (if you have permission to view the audit log) Changes to the notebook itself aren't automatically reflected. You need **Publish changes** to reflect them. ## URL sharing options {#share-options} From **Share**, you can generate a URL at the following units. * **Entire report** * **Individual page** * **Individual chart** For **Entire report**, you can configure the following options. | Item {.nowrap} | Choices / content | | --- | --- | | **Header** | Show Codatum logo and title / Show Codatum logo only. Defaults to showing the Codatum logo and title. | | **SQL block** | Show / Show results only / Hide. Defaults to showing it. | | **Hide sidebar** | When enabled, hides the [left sidebar](../../../../guide/screen-layout). Disabled by default. | | **Theme** | Light theme / Dark theme / Sync with system | You can also get the embed code from the same screen. ## Specification {#spec} * Public link pages have `noindex` set, which suppresses indexing by search engines. * Data at the time of publishing is saved and shown as a snapshot. * If expiration is enabled, published content is deleted once the specified number of days has passed since publishing. * A [workspace policy](../../../../workspace/access-and-security/policy#policy-settings) can disable creating and updating public links. * The number you can create has a limit that depends on your contract (see [Limits](../../../../reference/limits#plan-limits)). * A [workspace owner](../../../../workspace/administration/user#workspace-roles) can check the list of active public links from the global nav > **Workspace settings** > **Public links**. You can filter by keyword and open the source notebook or the public link. ## When you can't publish {#cannot-publish} Check the following. 1. Whether you have publish permission on the source notebook (notebooks accessed through a shared folder can't be published). 2. Whether you have publish permission on the connections used by the pages being published. 3. Whether creating and updating is disabled by a [workspace policy](../../../../workspace/access-and-security/policy#policy-settings). 4. Whether you've reached the limit on the number of public links (global nav > **Workspace settings** > **Usage**). --- --- url: 'https://docs.codatum.com/features/notebook/sharing/signed-embed/overview.md' description: >- Signed embed for embedding a notebook into an external app with an API key and token --- # Signed embed (Optional feature) A signed embed is a feature for embedding the content of a notebook, at the time it was published, into an external site or app. It's used together with the embedding destination's own authentication system, and doesn't require logging in to Codatum. Authentication uses an [API key](../../../../workspace/access-and-security/api-key) and a token issued server-side. Viewers can change parameters and re-run SQL. Downloads and the Explorer are controlled by publish options. Comments aren't available. See [Sharing](../overview#comparison) for a comparison of sharing methods. For integration steps, see [Integration steps](./integration). For data isolation per tenant, see [Multi-tenant](./multi-tenant). For embedding on the frontend, you can use the [Codatum Embed SDK](https://github.com/codatum/codatum-embed-js) (`@codatum/embed` / `@codatum/embed-react` / `@codatum/embed-vue`). ::: tip This is an **optional feature**. Depending on your contract, it might not be available. ::: ## Key features * [Publishing](#publish) / [Settings](#settings) * [Integration steps](./integration) * [Token issuance API](./issue-token) * [Multi-tenant](./multi-tenant) * [Use cases](./use-case) * [FAQ](./faq) ## Publishing {#publish} Publishing requires publish permission on the source notebook, and publish permission on the connections used by the pages being published. Notebooks accessed through a shared folder can't be published. 1. Open **Share** on the notebook screen, then select the **Signed embed** tab. 2. Select **Create signed embed**. 3. Configure the following, then select **Publish**. | Item {.nowrap} | Description | | --- | --- | | **Signed embed name** | The name of the embed. Defaults to the notebook name. You can also set an icon. | | **Published pages** | The pages to publish. At least one page other than a **section divider** is required. Defaults to all pages. | | **Embedded connections** | Automatically extracted from the pages being published. Publish permission on the target connections is required. | | **Enable downloads** | Lets embed viewers download the source data. Disabled by default. | | **Enable Explorer** | Lets embed viewers explore the source data. Disabled by default. | After publishing, you can do the following from the list. * Open the settings/preview screen from the name or **Settings**. * **Publish changes**: reflects changes to the notebook or to publish options. * **Compare with current notebook** * **Delete** Changes to the notebook itself aren't automatically reflected. You need **Publish changes** to reflect them. Changing downloads or the Explorer also requires republishing. ## Settings {#settings} On the settings screen, you can change the following. | Item {.nowrap} | Description | | --- | --- | | **Signed embed name** | The display name of the embed. | | **API keys granted permission** | The API keys that can be used to issue tokens. At least one is required. | | **Server-side parameters** | Parameters whose value is specified server-side when issuing a token. Parameters not specified here become client-side parameters. | | **Allowed origins** | The origins allowed to embed. Specify values starting with `http://` or `https://`. If unset, embedding is allowed from any origin. | | **Publish options** | The download and Explorer settings. Changing these requires republishing. | ### Server-side parameters {#server-side-params} For each parameter, you can choose one of the following. | Type {.nowrap} | Description | | --- | --- | | **Fixed value** | A value fixed server-side. Users can't change the value, and the input field is also hidden. | | **Initial value** | Sets an initial value, but users can change the value from the frontend's input field. | Changing a fixed value requires reissuing the token. See [Multi-tenant](./multi-tenant) for details. ## Specification {#spec} * The default token expiration is 3600 seconds (1 hour); the maximum is 86400 seconds (see [Limits](../../../../reference/limits#fixed-limits)). * If `cache_max_age` is omitted, the default is 86400 seconds. The maximum is also 86400 seconds. * The number you can create has a limit that depends on your contract (see [Limits](../../../../reference/limits#plan-limits)). * The **Signed embed** tab is shown when the signed embed feature is enabled for the workspace. ## When you can't publish {#cannot-publish} Check the following. 1. Whether you have publish permission on the source notebook (notebooks accessed through a shared folder can't be published). 2. Whether you have publish permission on the connections used by the pages being published. 3. Whether you've reached the limit on the number of signed embeds (global nav > **Workspace settings** > **Usage**). --- --- url: 'https://docs.codatum.com/features/notebook/sharing/signed-embed/integration.md' description: >- Publishing a signed embed, the token issuance API, and integrating with the Embed SDK --- # Integration steps The steps for integrating a signed embed into an external app. For a feature overview, see [Signed embed](./overview). ## Prepare {#prepare} 1. Open global nav > **Workspace settings** > **API keys**, then create an [API key](../../../../workspace/access-and-security/api-key). Keep the API key and API secret on hand. 2. Publish from **Share** > **Signed embed** on the notebook screen. 3. On the settings screen, add the API key you'll use to **API keys granted permission**. 4. If you need data isolation per tenant, or need to restrict the embedding domain, configure **Server-side parameters** or **Allowed origins**. You can check a sample token-issuance request and the embed URL from **Setup guide** on the settings screen. ## Issuing a token {#issue-token} Call the following API server-side. Handle the API secret server-side only, and don't include it in the frontend. For the same user (`token_user_id`) and the same fixed values, you can reuse the token within its expiration period. Reissue it when the user or a fixed value changes. See [Token issuance API](./issue-token) for the OpenAPI spec. The JSON URL is as follows. ```text https://api.codatum.com/api/notebook/spec.json ``` ### Request | Field {.nowrap} | Required {.nowrap} | Description | | --- | --- | --- | | `api_key` | Required | The API key. | | `api_secret` | Required | The API secret. | | `integration_id` | Required | The signed embed's ID. You can check this on the settings screen. | | `page_id` | Required | The ID of the page to display. You can check this on the settings screen. | | `token_user_id` | Required | An ID that uniquely identifies the user within the embedding app. Used for auditing and for access control of run results. Doesn't affect Codatum workspace permissions. | | `params` | Required | An array of server-side parameters. Each element has `param_id` and `param_value` (a JSON-stringified value). You must include every server-side parameter you've configured. Even if you don't use server-side parameters, send an empty array `[]`. | | `expires_in` | Optional | The token's expiration, in seconds. Defaults to 3600; the maximum is 86400. | | `cache_max_age` | Optional | The maximum cache duration, in seconds. Defaults to 86400; the maximum is 86400. 0 disables caching. | ### Response | Field {.nowrap} | Description | | --- | --- | | `token` | The issued token. | ## Embedding on the frontend {#embed} Use the [Codatum Embed SDK](https://github.com/codatum/codatum-embed-js) to embed on the frontend. The packages are as follows. * [`@codatum/embed`](https://github.com/codatum/codatum-embed-js/tree/main/packages/embed#readme): the core SDK * [`@codatum/embed-react`](https://github.com/codatum/codatum-embed-js/tree/main/packages/embed-react#readme): a wrapper for React * [`@codatum/embed-vue`](https://github.com/codatum/codatum-embed-js/tree/main/packages/embed-vue#readme): a wrapper for Vue You can check the embed URL (`embedUrl`) from **Setup guide** on the settings screen. See each package's README for installation, options, and events. ```ts import { createEmbed } from '@codatum/embed'; const embed = createEmbed({ container: '#dashboard', embedUrl: 'https://app.codatum.com/protected/workspace//notebook/', tokenProvider: async () => { const res = await fetch('/api/codatum/token', { method: 'POST' }); const data = await res.json(); return { token: data.token }; }, }); await embed.init(); ``` `tokenProvider` is a callback where your own server issues and returns a token. It's called on initialization, on reload, and when the token is refreshed before it expires. See the [FAQ](./faq) for common questions about integration. --- --- url: 'https://docs.codatum.com/features/notebook/sharing/signed-embed/issue-token.md' description: The issueToken API for issuing signed embed tokens --- # Token issuance API An API for issuing tokens for signed embeds. For the integration flow and a description of the request/response, see [Integration steps](./integration#issue-token). You can get the machine-readable OpenAPI spec from the following URL. ```text https://api.codatum.com/api/notebook/spec.json ``` --- --- url: >- https://docs.codatum.com/features/notebook/sharing/signed-embed/multi-tenant.md description: >- Configuring a signed embed to isolate data per tenant using server-side parameters --- # Multi-tenant In a signed embed, using **fixed values** for server-side parameters lets you isolate the data each tenant in the embedding destination can view. You can reuse a single notebook for multiple tenants while ensuring each tenant can only view their own data. See [Signed embed](./overview#server-side-params) for the parameter types, [Integration steps](./integration) for the integration steps, and [Use cases](./use-case) for concrete design examples. ## Roles of each parameter {#param-roles} | Type | Purpose | | --- | --- | | Server-side parameter **fixed value** | A condition, such as a tenant ID, that viewers must not be able to change. It's not shown in the input form. | | Server-side parameter **initial value** | A value such as the store ID shown initially. The initial value is specified server-side, and can be changed from the input form afterward. | | Client-side parameter | A condition, such as a date range or category, specified dynamically from the input form or the embedding app. | ::: warning On the SQL side, always include the fixed-value parameter in your filter conditions. If you only filter on a lower-level identifier, such as a store, you might unintentionally allow access to another tenant's data. ::: ## Configuration examples {#examples} ### Using the input form on the signed embed side {#embed-form} 1. Make the tenant ID a **fixed value**, the initially displayed store ID an **initial value**, and things like the date range client-side parameters. 2. Issue a token server-side, including the fixed value and initial value in `params`. 3. Pass the client-side parameters when initializing the embed. 4. Viewers can change the initial value and the client-side parameters from the input form. For details, see [Use cases: Configuration example A](./use-case#example-a). ### Managing parameters on the embedding app side {#app-managed} 1. Make the tenant ID a **fixed value**, and everything else client-side parameters. 2. Issue a token server-side, including the fixed value in `params`. 3. Enable `hideParamsForm` when initializing the embed, and pass the values managed by the embedding app as client-side parameters. 4. To update the conditions, reuse the same token and resend the full set of client-side parameters. You can't send only the diff. 5. If the same viewer uses the same fixed value, the token can be reused within its expiration period. For details, see [Use cases: Configuration example B](./use-case#example-b). ### Updating a fixed value {#update-fixed} If you also make something like the store ID a **fixed value**, changing the target store requires reissuing the token. 1. Reissue the token server-side, specifying the new fixed value. 2. Send the new token and the full set of client-side parameters to the embed. 3. If you want to preserve client-side parameters the viewer changed before the redraw, record the change notifications sent from the embed and include them when resending. For details, see [Use cases: Configuration example C](./use-case#example-c). --- --- url: 'https://docs.codatum.com/features/notebook/sharing/signed-embed/use-case.md' description: Design examples for isolating data per tenant with a signed embed --- # Use cases Design examples for a signed embed, assuming a retail-support SaaS. For a summary of parameter roles, see [Multi-tenant](./multi-tenant); for publishing and settings, see [Signed embed](./overview); for integration steps, see [Integration steps](./integration). For code examples, also see the README of the [Codatum Embed SDK](https://github.com/codatum/codatum-embed-js/tree/main/packages/embed#readme). ## Scenario {#scenario} Assume a SaaS that supports retail store operations, embedding a dashboard of sales and KPIs per store. When a store manager or an area manager logs in, only the information related to their own store is shown. ## Notebook parameters {#params} Assume the source notebook has the following parameters. The parameter names are examples; they aren't required names. * `tenant_id` * The tenant ID the logged-in user belongs to. * [Text input](../../parameter/types#text-input). * `store_id` * The ID of the store to display. * [Text select](../../parameter/types#text-select). The choices are the store IDs within the tenant specified by `tenant_id`. * `date_range` * The aggregation period. * [Date range](../../parameter/types#date-range). The default value is a [relative date](../../parameter/relative-date), 7 days ending yesterday. * `product_category` * The product category to aggregate. * [Text multi select](../../parameter/types#text-multi-select). When nothing is selected, the SQL conditions show all categories. ## Configuration example A: using the signed embed's own form {#example-a} ### Notebook design assumptions * Fix `tenant_id` to restrict the data that can be accessed. * The SQL that extracts data must always include `tenant_id` as a filter condition. * Even when extracting store data, include `tenant_id` as a condition in addition to `store_id`, so that another tenant's store data can't be extracted. * Design `date_range` and `product_category` so any value can be specified. ### Parameter configuration * `tenant_id`: **server-side parameter fixed value** * `store_id`: server-side parameter initial value * `date_range`: client-side parameter * `product_category`: client-side parameter ### Flow up to display 1. Issue a token server-side. * Specify the user's `tenant_id` as the fixed value. * Among the stores tied to `tenant_id`, specify the `store_id` to display initially as the initial value. 2. Render initially on the frontend. * In the return value of the [Embed SDK](https://github.com/codatum/codatum-embed-js/tree/main/packages/embed#readme)'s `tokenProvider`, include the following client-side parameters in `params`. * For `date_range`, configure it to use the default value as the initial value, so the relative date is recalculated (see [Relative dates](../../parameter/relative-date#signed-embed)). * Specify an empty array as the initial value for `product_category`. 3. The user operates the dashboard. * The user can change `store_id`, `date_range`, and `product_category` from the input form. ## Configuration example B: managing parameters on the embedding app side {#example-b} ### Notebook design assumptions Same as configuration example A. ### Parameter configuration * `tenant_id`: **server-side parameter fixed value** * `store_id`: client-side parameter * `date_range`: client-side parameter * `product_category`: client-side parameter ### Flow up to display 1. Issue a token server-side. * Specify the user's `tenant_id` as the fixed value. 2. Render initially on the frontend. * Enable `displayOptions.hideParamsForm` to hide the parameter form. * In the return value of `tokenProvider`, include the `store_id`, `date_range`, and `product_category` managed by the embedding app in `params`. 3. The user operates the dashboard. * To update the display based on a condition change on the embedding app side, use the following steps. * Reuse the token used for the initial render, and reload the embed (for example, via `reload`) with the full set of updated client-side parameters included in `params`. * Send the full set (`store_id`, `date_range`, `product_category`), not just the diff. * If the same user uses the same fixed value, the token can be reused within its expiration period. ## Configuration example C: updating a server-side parameter's fixed value {#example-c} ### Notebook design assumptions * Fix both `tenant_id` and `store_id` to restrict the data that can be accessed. * Unlike configuration example A, this assumes `store_id` also needs to be fixed server-side. * Design `date_range` and `product_category` so any value can be specified, as in configuration example A. ### Parameter configuration * `tenant_id`: **server-side parameter fixed value** * `store_id`: **server-side parameter fixed value** * `date_range`: client-side parameter * `product_category`: client-side parameter ### Flow up to display 1. Issue a token server-side. * Specify the user's `tenant_id` and the `store_id` to display initially as fixed values. 2. Render initially on the frontend. * In the return value of `tokenProvider`, include the following client-side parameters in `params`. * For `date_range`, configure it to use the default value as the initial value, so the relative date is recalculated (see [Relative dates](../../parameter/relative-date#signed-embed)). * Specify an empty array as the initial value for `product_category`. 3. The user operates the dashboard. * `store_id` is a fixed value, so it can't be changed from the input form. Provide a store-switching UI on the embedding app side. * To change stores and re-render, reissue the token with the new `store_id`, then send the new token and the full set of client-side parameters. * Changing a fixed value requires reissuing the token. * Send the full set of client-side parameters (`date_range`, `product_category`), not just the diff. * If you want to preserve values the user changed before the redraw, record them using the Embed SDK's `paramChanged` event (`onParamChanged` in React / Vue) and include them when resending. * `date_range` and `product_category` can be changed from the input form. --- --- url: 'https://docs.codatum.com/features/notebook/sharing/signed-embed/faq.md' description: Frequently asked questions about signed embed --- # FAQ Questions about configuring and integrating a signed embed. For step-by-step details, see [Integration steps](./integration); for tenant isolation, see [Multi-tenant](./multi-tenant); for design examples, see [Use cases](./use-case). ## `Missing param: xxx` is shown when issuing a token When issuing a token, the request must include all of the server-side parameters you've configured. The missing parameter ID is shown as `xxx`. ## `The following parameters must be set by the server` is shown when sending a client-side parameter You're trying to change a server-side parameter from the client side. Changing a server-side parameter requires issuing a new token. ## Sending a client-side parameter doesn't change the value Check the following. 1. Whether the target parameter is configured as a server-side parameter. 2. Whether `param_value` is a valid JSON string. 3. Whether `param_id` matches an existing parameter ID. ## Can't embed after configuring allowed origins Check whether the origin of the page embedding it matches one of the origins you set in **Allowed origins**. If you've configured origins, you can't open the embed by attaching the token directly to the URL. ## No API key is granted Add the API key you want to use for issuing tokens to **API keys granted permission** on the settings screen. You can't issue a token if none is configured. ## Relative dates don't behave as expected Relative dates aren't recalculated for server-side parameters. Treat it as a client-side parameter, and configure it to use the default value as the initial value. See [Relative dates](../../parameter/relative-date) for details. --- --- url: 'https://docs.codatum.com/features/notebook/faq.md' description: Frequently asked questions about notebooks --- # FAQ Frequently asked questions about notebooks. For details, see the page for each feature. ## A notebook feels slow {#performance} If a notebook is slow to load, or edits take a while to appear, the notebook or page might be too large. ### Units of loading and rendering {#processing-units} Notebook processing works in the following units. | Process {.nowrap} | Unit {.nowrap} | Description | | --- | --- | --- | | Loading | Notebook | When you open a notebook, the contents of all pages are loaded | | Collaborative editing sync | Notebook | The entire notebook is synced together | | Rendering | Page | Only the open page is rendered | Switching pages doesn't reload the notebook; it only re-renders the page. If you [reference an SQL block on another page](./doc-page/sql-block#sql-block-ref), changing that other page can also trigger a re-render. ### Checking the current size {#check-size} You can check the notebook size in **Size** after opening **About this notebook** in [the header](../../guide/screen-layout) inside the notebook. When the notebook size exceeds 1MB, a warning appears at the bottom of the screen. When it exceeds 10MB, editing is disabled. Even if the notebook hasn't reached the 10MB size limit, larger notebooks affect performance, so consider splitting around 1MB. ### Narrowing down the cause from symptoms {#diagnose} | Symptom {.nowrap} | Likely cause | What to do | | --- | --- | --- | | Opening the notebook is slow | The whole notebook is large | [When the whole notebook is slow](#slow-notebook) | | Editing or interaction feels slow Switching pages is slow | That page has a lot of content | [When only a specific page is slow](#slow-page) | Opening a notebook includes both loading the whole notebook and rendering the page. If it's still slow after you switch to a lighter page, the whole notebook is likely the cause. If it's slow only on a specific page, that page is likely the cause. ### When the whole notebook is slow {#slow-notebook} Because the whole notebook is loaded and synced, adding pages and blocks makes opening and collaborative editing slower. References between SQL blocks and parameters are also calculated across the whole notebook. Instead of keeping adding pages to one notebook, split notebooks by analysis theme or use case. (Consider splitting around about 10 pages per notebook.) To split an existing notebook, follow these steps. 1. Export the notebook you want to split. 2. For each destination notebook, select the pages to include and import them as a new notebook. 3. If you keep the original notebook, delete the pages you've already moved. See [Export and import](./export#import-as-new) for the steps. When you split notebooks, you might end up writing the same SQL in multiple notebooks. Save shared SQL as a [saved query](../saved-query/overview) and reference it from each notebook. ::: tip A notebook keeps internal data for collaborative editing. Codatum cleans up unused data automatically, but it doesn't remove all of it. As a result, repeated editing can make the notebook larger than its visible content. If you [export](./export) the notebook and import it as a new notebook, that internal data isn't carried over, so the size can become smaller without changing the content. ::: ### When only a specific page is slow {#slow-page} Opening a page renders all blocks and charts on that page. The more blocks and charts you place on one page, the longer display and editing can take. In this case, [add a page](./overview#add-page) and split the content. Pages that aren't open aren't rendered, so you can reduce the amount of rendering per page. Within the same notebook, you can [reference an SQL block on another page](./doc-page/sql-block#sql-block-ref), so you can keep SQL references when you split pages. ## A notebook can't be edited because it exceeds the size limit {#size-limit} You can't edit a notebook when its size exceeds 10MB. See [Limits](../../reference/limits#fixed-limits). You can still [export](./export) a notebook you can't edit. Import only the pages you need into a new notebook to continue editing. See [Export and import](./export#import-as-new) for the steps. ## Column names aren't suggested in a SQL block {#column-suggest} Column name suggestions are available only when you use a [table](./doc-page/sql-block#references) reference or a [reference to another SQL block](./doc-page/sql-block#sql-block-ref). Suggestions aren't available when you write a table ID as a string, or when you reference a [saved query](../saved-query/overview). See [SQL block](./doc-page/sql-block#constraints) for details. --- --- url: 'https://docs.codatum.com/features/workflow/overview.md' description: Scheduled runs and automation through steps --- # Workflow (Beta) (Optional feature) Workflow runs the steps of a saved query or report in order, on a schedule, and connects them to follow-up actions like email, Slack, or an LLM. Open it from [global nav](../../guide/screen-layout) > **Workflows**. Viewing and editing are available to the users and groups set as **owners** of the workflow. Creating a workflow requires [workspace editor](../../workspace/administration/user#workspace-roles) permission or higher. See [Workflow permissions](../../permissions/resources/workflow) for details. ::: info This feature is in **beta**. The specification might change without notice. ::: ::: tip This is an **optional feature**. Depending on your contract, it might not be available. ::: ## Key features * [Creating and managing](#create-manage): Create, edit, activate/deactivate, run manually, duplicate, and delete. * [Schedule](#schedule): Hourly / daily / weekly / monthly, with a time zone. * [Steps](./steps): Run Query / Run Report / Screenshot / Email / LLM / Slack. * [Execute-if conditions](./template-variables#execute-if) and [template variables](./template-variables): Pass results from earlier steps to later ones, and run steps conditionally. * [Run history](#run-history): Review past runs and the outcome of each step. * [Owners](../../permissions/resources/workflow): The users and groups who can view and edit the workflow. * [Use cases](./use-case): Example setups such as Slack notifications. ## Screen layout | Screen {.nowrap} | Contents | | --- | --- | | List | Shows name, status, trigger, steps, last run, updated date, and owners. Includes **New workflow** and search | | Create/edit | Set **General**, **Trigger** (**Schedule**), and steps | | Detail | Has **Workflow settings** and **Run history** tabs. You can **Run now** / **Edit** / **Activate** or **Deactivate** / **Delete** | The row menu in the list also has **Edit** / **Duplicate** / **Deactivate** or **Activate** / **Delete**. ## Creating and managing {#create-manage} ### Creating You can create a workflow in either of the following ways. Creating requires [workspace editor](../../workspace/administration/user#workspace-roles) permission or higher. 1. Open global nav > **Workflows** and select **New workflow**. 2. From the [right sidebar](../../guide/screen-layout) > **Workflows** on a [query](../saved-query/overview) detail, select **New workflow**. In this case, the workflow opens with step 1 already set to Run Query for that query. A newly created workflow starts as **Inactive**. To start running on a schedule, **Activate** it after saving. The creator is automatically set as an owner. ### Editing and saving Open the editor from **Edit** on the detail screen or in the list. Select **Save** to update the definition. ### Activating and deactivating | Action {.nowrap} | Description | | --- | --- | | **Activate** | Sets the status to **Active** and runs it on the configured schedule. If there are unsaved changes, save first. You can't activate a workflow if you've reached the limit on active workflows | | **Deactivate** | Sets the status to **Inactive**; scheduled runs stop | You can run a workflow manually with **Run now** even when it's **Inactive**. If the editor has unsaved changes, save first. ### Duplicating and deleting | Action {.nowrap} | Description | | --- | --- | | **Duplicate** | Creates a new, **Inactive** workflow with `(copy)` added to the name. Requires create permission | | **Delete** | Deletes the workflow after confirmation. It stops running, and its run history also becomes inaccessible | ## Schedule {#schedule} Configure this under **Trigger** > **Schedule** in the editor. | Item {.nowrap} | Description | | --- | --- | | **Repeat every** | Choose a frequency: `hour` / `day` / `week` / `month` | | **Start minute** | For `hour`. Choose from `00` / `10` / `20` / `30` / `40` / `50` | | **Start time** | For `day` / `week` / `month`. Set the hour (`00`-`23`) and minute (`00` / `10` / `20` / `30` / `40` / `50`) | | **Day of the week** | For `week`. Select one or more days | | **Date** | For `month`. Choose one day from `1`-`28` | | Time zone | Set together with **Start minute** / **Start time** | ## Status ### Workflow | Label {.nowrap} | Meaning | | --- | --- | | **Active** | Scheduled to run | | **Inactive** | Not scheduled to run | ### Run (job) | Label {.nowrap} | Meaning | | --- | --- | | **RUNNING** | In progress. Select **Stop** to cancel | | **SUCCESS** | Completed | | **FAILED** | Failed | | **CANCELLED** | Cancelled, for example by stopping it | ### Step result | Label {.nowrap} | Meaning | | --- | --- | | **PENDING** | Not started yet | | **RUNNING** | In progress | | **SUCCESS** | Completed | | **ERROR** | Failed | | **SKIPPED** | Skipped due to an [execute-if condition](./template-variables#execute-if) | | **CANCELLED** | Cancelled | The trigger shown for a run is the user for manual runs, and **Schedule** for scheduled runs. ## Run history {#run-history} The **Run history** tab on the detail screen shows past runs. ## Constraints * A workflow can have up to 20 steps ([Limits](../../reference/limits#fixed-limits)). * A workflow can have up to 30 owners ([Limits](../../reference/limits#fixed-limits)). * The maximum number of active workflows depends on your contract ([Limits](../../reference/limits#plan-limits); check under global nav > **Workspace settings** > **Usage**). * Workflow names must be 1-100 characters, and descriptions up to 1,000 characters. ## Permissions See [Workflow permissions](../../permissions/resources/workflow) for the conditions for each action. The list shows workflows you own. A [workspace owner](../../workspace/administration/user#workspace-roles) can see every workflow in the workspace in the list. --- --- url: 'https://docs.codatum.com/features/workflow/steps.md' description: Actions and settings you can add to a workflow --- # Steps A step is a unit of processing that a workflow runs in order from top to bottom. Add one from **Add step** in the editor, and drag to reorder. See [Limits](../../reference/limits#fixed-limits) for the maximum number of steps. Steps are grouped as follows when you add them. | Group {.nowrap} | Contents | | --- | --- | | **Codatum actions** | Run Query / Run Report / Screenshot / Email / LLM | | **Integrations** | Slack integrations you've already created (shown by integration name) | Each step can have an [execute-if condition](./template-variables#execute-if). For embedding values in the body, messages, and so on, see [Template variables](./template-variables). ## Run Query Runs the specified [saved query](../saved-query/overview) and makes the result available to later steps. | Item {.nowrap} | Description | | --- | --- | | **Query** | The saved query to run. You select it together with its connection | Later steps can reference up to 20 rows of the result through template variables (see [Limits](../../reference/limits#fixed-limits)). For example variables, see [Template variables](./template-variables#variables). If you create a workflow from the right sidebar on a query detail, this step opens already configured. ## Run Report (Beta) Runs a [report](../notebook/sharing/report/overview). Placing it right before a Screenshot step lets you capture the latest results. ::: info This feature is in **beta**. The specification might change without notice. ::: | Item {.nowrap} | Description | | --- | --- | | **Report** | The report to run | | **Use default parameters** | Off by default. When on, resets parameters to the report's default values before running | | **Timezone for relative dates** | Shown when **Use default parameters** is on. UTC is used if not set | | **Update report after run** | Off by default. When on, saves the run's results back to the report | ## Screenshot (Beta) Captures a specific report page as a PNG. The resulting file URL can be used in a later Email or Slack attachment. ::: info This feature is in **beta**. The specification might change without notice. ::: | Item {.nowrap} | Description | | --- | --- | | **Report** | The target report | | **Page** | The page to capture | | **Run ID** | The ID of the report run. If a Run Report step immediately precedes this one, a template variable referencing that step's `runId` might be filled in automatically | | **Format** | **Type** is PNG only. **Theme** is **Light** / **Dark** (default is light). **Locale** is `en-US` / `ja-JP` (defaults based on browser language) | ## Email Sends email to users or groups in the workspace. | Item {.nowrap} | Description | | --- | --- | | **To** | Choose 1-20 users or groups ([Limits](../../reference/limits#fixed-limits)) | | **Subject** | Up to 200 characters. Supports [template variables](./template-variables) | | **Body** | Sent as HTML. Supports [template variables](./template-variables) (up to 5,000 characters) | | **Attachment** | Optional. You can specify a file URL from an earlier step, such as Screenshot, using a template variable | The sender is `noreply@workflow.codatum.com`. The email footer includes a link back to the workflow. ## LLM Runs natural language processing using an [AI profile](../../workspace/codatum-ai/ai-profile). Not selectable if Codatum AI is disabled for the workspace. When the workflow runs, the context (notebooks or folders) linked to the AI profile isn't loaded. | Item {.nowrap} | Description | | --- | --- | | **AI Profile** | The AI profile to use. Create and review profiles under **AI Profile settings** | | **Prompt** | The content sent to the LLM. Supports [template variables](./template-variables) (up to 5,000 characters) | ## Slack {#slack} Sends a message to a specified channel. Requires a Slack integration to be created first. ### Creating the integration 1. Open global nav > **Workspace settings** > [**Options**](../../workspace/overview#options) > **Integrations**. 2. Select **New integration**, then choose Slack. 3. In **Create Slack integration**, select **Connect** and approve on the Slack side. Add the Codatum app to the destination channel in Slack with `/invite @Codatum`. If a channel doesn't appear in the list, check that the app has been invited there too. You can also open the same settings screen from **Create integration** when adding a step. ### Settings The display name is the integration's name. | Item {.nowrap} | Description | | --- | --- | | **Channel** | The destination. Select **Refresh channels** to fetch the list again | | **Message Text** | Supports [template variables](./template-variables) (up to 5,000 characters). For formatting syntax, see [Slack's message formatting guide](https://docs.slack.dev/messaging/formatting-message-text/) | | **File** | Optional. You can specify a file URL from an earlier step | | **Thread (optional)** | Specify the message timestamp from an earlier Slack step to reply in that thread | | **Include Link to Codatum** | On by default. Adds a link back to the workflow. Viewing the link requires owner permission | --- --- url: 'https://docs.codatum.com/features/workflow/template-variables.md' description: Inserting variables and writing execute-if conditions --- # Template variables In a workflow's message body, prompt, execute-if condition, and similar fields, you can use template variables to embed results and run information from earlier steps. Select **Insert variable** in the input field to choose from the available variables. The syntax is based on the [Liquid template language](https://shopify.github.io/liquid/). The maximum template string length depends on the field (up to 5,000 characters for body/prompt fields, and up to 100 characters for execute-if conditions). ## Variables {#variables} **Insert variable** lets you choose from the following groups. You can only reference the output of steps before the current one. Templates wrap a path in double curly braces. :::: tip ::: v-pre Example: the workflow run ID is `{{ run.id }}`, and the query's row count is `{{ query.rowCount }}`. ::: :::: ### Workflow run | Label {.nowrap} | Path | Description | | --- | --- | --- | | **Workflow Run ID** | `run.id` | The ID of the run | | **Start Time** | `run.startedAt` | The start time of the run | | **Trigger Type** | `run.trigger` | `schedule` or `manual` | ### Earlier steps Suggested variables depend on the step type. The identifier is the step ID (for example, `query`, or `query_1` if there are multiple). | Step {.nowrap} | Key variables | | --- | --- | | Run Query | **Row count** (`rowCount`), each column of the **First Row**, **Rows** (a loop over rows, up to 20) | | Run Report | **Run ID** (`runId`) | | Screenshot | **File URL** (`fileUrl`), for attachments | | Slack | **Message Timestamp** (`messageTs`), for specifying a thread | | LLM | **Text**, and usage (prompt/completion/total tokens) | Column suggestions for Run Query's **First Row** appear if you've run the target query and saved it beforehand. ### Example An example that includes the row count and the first few rows of a query result in a message. You can insert similar content from **Row count** and **Rows** in **Insert variable**. ```liquid Count: {{ query.rowCount }} {% for row in query.rows limit:5 %} - {{ row.account_name }} {% endfor -%} ``` ## Execute-if condition {#execute-if} Writing an expression in a step's optional **Execute if** field runs that step only when the condition is true. The placeholder example compares whether the row count is greater than 0 (you can enter this by choosing **Row count** in **Insert variable**). The condition is evaluated after template variables are expanded. If left blank, the step runs when there's no failure in earlier steps, and is skipped otherwise (it runs only on implicit success). You can use the following functions in a condition expression. | Function {.nowrap} | Meaning | | --- | --- | | `success()` | True when there's no failure in earlier steps | | `failure()` | True when an earlier step failed. Useful for error-notification steps | | `always()` | Always true. Useful for steps you want to run even after a failure | You can combine these with `AND` / `OR` and comparisons (`>` / `=` and so on). A condition that doesn't include a status function is skipped if an earlier step failed. --- --- url: 'https://docs.codatum.com/features/workflow/use-case.md' description: Practical examples using Workflow --- # Use cases Example workflow setups. For a feature overview, see [Workflow](./overview); for step details, see [Steps](./steps); and for variable syntax, see [Template variables](./template-variables). ## Notifying Slack {#slack-notification} An example that prepares a saved query counting accounts created within the last day, and notifies Slack only when new accounts were registered. The overall setup is as follows. * **Trigger**: Schedule (daily at 10:00) * **Step 1**: Run Query (fetches accounts from the last day) * **Step 2**: Slack (notifies only if there's at least one result) ### 1. Prepare a saved query {#prepare-query} Prepare a [saved query](../saved-query/overview) with SQL that returns accounts created within the last day, based on their creation timestamp. ```sql SELECT * FROM `codatum-example.example.accounts` WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY) ORDER BY created_at DESC ``` ### 2. Create the workflow and set the trigger {#create-workflow} [Create a workflow](./overview#create-manage) and set the following under **Trigger** > **Schedule**. * **Repeat every**: `day` * **Start time**: `10:00` (for example, using Japan Standard Time as the time zone) ::: tip If you create it from the [right sidebar](../../guide/screen-layout) > **Workflows** on the query detail, it opens with step 1 already set to Run Query for that query. ::: ### 3. Configure Run Query for step 1 {#step-run-query} If you created the workflow from the Workflow screen, select the saved query you prepared. If you created it from the query detail, it's already selected. ### 4. Configure Slack for step 2 {#step-slack} Create a [Slack integration](./steps#slack) beforehand, and add the app to the destination channel. | Item {.nowrap} | Example setting | | --- | --- | | **Channel** | The notification destination (for example, `notification_codatum`). Channels with the app already added appear in the list | | **Message Text** | See the [message text example](#message-body) below | | **Thread (optional)** | If you have multiple Slack steps, specifying an earlier step's message timestamp replies in that thread | | **Include Link to Codatum** | Adds a link back to the workflow. Viewing the link requires owner permission | | **Execute if** | See the [execute-if example](#execute-if-example) below | #### Message text example {#message-body} You can choose **Row count**, **First Row**, and **Rows** from **Insert variable**. :::: tip ::: v-pre * Choosing `account_name` under **First Row** inserts `{{ query.rows[0].account_name }}`. * Choosing **Rows** inserts a loop over rows. Each iteration references `row` (for example, `{{ row.account_name }}`). ::: :::: An example that includes the count and up to the first 5 rows. ```liquid Accounts created in the last day: {{ query.rowCount }} Recently created accounts (up to 5 shown) {% for row in query.rows limit:5 %} Account name: {{ row.account_name }} Created at: {{ row.created_at }} {% endfor -%} ``` #### Execute-if example {#execute-if-example} To send to Slack only when step 1's query has results, set the following expression as **Execute if**. If the condition isn't met, this step doesn't run. See also [Execute-if condition](./template-variables#execute-if). ```liquid {{ query.rowCount }} > 0 ``` You can enter this by choosing **Row count** in **Insert variable**. `query` holds step 1's Run Query output. If you have multiple Run Query steps, it becomes `query_1` and so on. See [Template variables](./template-variables#variables) for details. ### 5. Save and activate {#activate} **Save**, then **Activate**. Scheduled runs begin. --- --- url: 'https://docs.codatum.com/features/ai-agent/overview.md' description: >- An AI agent that performs data analysis and notebook operations from natural language --- # AI agent (Beta) (Optional feature) The AI agent takes natural language instructions and autonomously performs data analysis and notebook creation and editing. It can reference the catalog and notebook content while running SQL, checking results, and creating charts. The model, permissions, and fixed context it uses are managed through an [AI profile](../../workspace/codatum-ai/ai-profile). For preparing context that's loaded automatically, see [Agent context](./agent-context). If you're using the legacy AI Assistant, see [AI Assistant](../ai-assistant/overview). ::: info This feature is in **beta**. The specification might change without notice. ::: ::: tip This is an **optional feature**. Depending on your contract, it might not be available. ::: ## Key features * [Sending data to the LLM](#llm-data): How data is handled for training purposes, and what information might be sent to the LLM. * [Enabling it](#enable): Enable the AI agent under **AI feature settings** in workspace settings. * [Display modes](#display-modes): Side panel / full page. * [Canvas](#canvas): View, share, and download pages created by the AI agent. * [Operation modes](#operation-modes): **Ask** (analysis) / **Agent** (including creation and editing). * [Specifying context](#mention-context): Use `@` to specify tables, notebooks, saved queries, and more. * [Agent context](./agent-context): The `.agent` folder or page, and context from an AI profile. * [Message queue](#message-queue): Queue, edit, or send a message ahead of turn while a run is in progress. * [Plan & Todos](#plan-and-todos): Review the Plan and Todos for the current session. * [Conversation history summary](#conversation-summary): Summarize a long conversation history. * [User settings](#user-settings): Auto-approving SQL, auto-loading context, language, and more. * [AI profile](../../workspace/codatum-ai/ai-profile): Manage the model, permissions, and fixed context used. * [Agent usage](../../workspace/codatum-ai/agent-usage): Check session and token usage. * [Agent connectors](../../workspace/codatum-ai/agent-connectors): Integrations with external tools (MCP / API). ## Sending data to the LLM {#llm-data} Only external LLM services that contractually guarantee your input data won't be used for training are used. If you want to use your own API key, you can configure this under **Custom** in [AI profile](../../workspace/codatum-ai/ai-profile#types). As the AI agent analyzes and processes data, it might send table data, SQL execution results, and similar information to the LLM service. Check your organization's AI usage policy before using this feature. ## Enabling it {#enable} Enabling AI features requires [Workspace Owner](../../workspace/administration/user#workspace-roles) permission. 1. Open [global nav](../../guide/screen-layout) > **Workspace settings** > **AI feature settings**. 2. Turn on AI features overall using the switch at the top of the screen. 3. Turn on **AI Agent** under **Available AI features**. You can also individually enable the following features on the same screen. | Feature {.nowrap} | Description | | --- | --- | | **AI Agent** | Performs data analysis, SQL execution, chart creation, and more from natural language | | **AI code completion** | Provides inline SQL completion within a SQL block | | **AI name suggestion** | Automatically suggests names for SQL and charts | ## Opening it {#open} You can open it in any of the following ways. 1. Open [global nav](../../guide/screen-layout) > **AI Agent** (full page). 2. Open the **AI Agent** icon at the bottom right of the screen (side panel). 3. Open the side panel with the **AI Assistant** shortcut (⌘+L / Ctrl+L by default; see [Keyboard shortcuts](../../account/settings/keyboard-shortcut)). 4. Select **Mention in the AI agent** from a SQL block in a notebook. If it isn't enabled, **AI Agent is disabled** is shown, and you can go to the enablement screen from **Manage settings**. ## Display modes {#display-modes} | Display {.nowrap} | How to open | Description | | --- | --- | --- | | Side panel | **AI Agent** at the bottom right of the screen | Makes it easy to use the notebook you're viewing as context | | Full page | [Global nav](../../guide/screen-layout) > **AI Agent** | Lets you view chat content in a larger area. You can also get here from **Session info** > **Open in full page mode** in the side panel | ## Canvas {#canvas} The AI agent can present analysis results and other content as an HTML Canvas. Each Canvas receives its own URL when it's created and remains available after its original session ends. You can open a Canvas preview from the chat. In the preview, you can select **Open in a new tab** from the menu to view the displayed version on its dedicated page. The owner can switch versions, and switching versions also updates the page URL to that version. A URL without a version opens the latest version. If you can only view the shared version, such as a viewer or someone using a public link, that version is shown and the version is removed from the URL. The owner can change sharing settings from **Share**. In the AI agent's full page, the preview appears beside the chat. From the Canvas in chat, the preview, and the dedicated URL page, you can select **Download HTML** or **Download PDF** from **Download** to save the content. The PDF uses A4 portrait, and people viewing a public link can download it without signing in. Get the dedicated URL from **Share** > **Copy link**. Opening that URL shows a page with only the Canvas. If the Canvas is shared with **Anyone with the link**, people can view it without signing in. Opening a restricted Canvas shows a sign-in path that returns to the same URL. If you are signed in and can use the workspace, the logo at the top left takes you to the workspace home. In a workspace where the AI agent is available, Workspace Viewers and higher see the AI agent launcher. Workspace Guests do not see it. When you open the AI agent from a Canvas page, it uses the displayed Canvas as context. Owners can ask the agent to read or edit the Canvas. Viewers can ask it to read the Canvas but not edit it. The owner can also change sharing settings from this page and switch versions. If the AI agent session open on this page creates a new version, the page switches to the latest version and drops the version from the URL. It doesn't switch when the agent isn't open or a different session is open. If you need to set up multi-factor authentication, the Canvas page shows the setup path regardless of whether the Canvas is public. If a temporary problem prevents the workspace from loading, you can retry from the same URL. ### Sharing settings {#canvas-sharing} The owner can change these settings under **Share**. | Item {.nowrap} | Description | | --- | --- | | **People with access** | Grants view access to users, groups, or all workspace members. | | **General access** | Choose **Only people with access** or **Anyone with the link**. If you select **Anyone with the link**, people can use the same URL without signing in. You can't select it if [workspace policy](../../workspace/access-and-security/policy#policy-settings) prevents public link creation. | | **Shared version** | Selects the version that viewers see. While **Anyone with the link** is selected, a fixed version is required, so you can't select **Latest**. | Editing a Canvas doesn't automatically move a fixed shared version forward. To share newer content, change **Shared version** to the newer version. When people other than you can view the Canvas, the version switcher labels the version they see as **Shared**. If **Latest** is selected, the current latest version gets the label. ## Operation modes {#operation-modes} You can switch between **Ask** and **Agent** at the bottom left of the chat input field. | Mode {.nowrap} | Description | | --- | --- | | **Ask** | Performs data analysis, including running SQL. Doesn't edit notebooks or the catalog | | **Agent** | Performs every operation, including creating and editing notebooks. Before editing, an **AI edit** [version](../notebook/version#kinds) is created automatically, so you can revert it | Users without edit permission on the notebook can't select **Agent** and are limited to **Ask**. ## Specifying context {#mention-context} In the chat input field, use `@` to specify what you want the AI agent to reference. | Target {.nowrap} | Description | | --- | --- | | **Table** | A table in the catalog | | **Notebook** | A notebook in the workspace | | **Saved Query** | A saved query | | **SQL Block** | A SQL block in the notebook you currently have open (when candidates exist) | | **Chart** | A chart in the notebook you currently have open (when candidates exist) | ## Chat screen actions {#chat-actions} You can perform the following actions from the header. | Action {.nowrap} | Description | | --- | --- | | **New chat** | Starts a new session | | **Chat history** | Lists past sessions and lets you switch between them | | **Session info** | Check the start time, **Total tokens**, and more. From the side panel, you can also select **Open in full page mode** | | **Close** | Closes the side panel (in side panel mode) | In the chat input field, you can change the following settings in addition to the operation mode. * The connection to prefer (default is `Auto`, letting the agent choose) * **Settings** ([user settings](#user-settings)) * **AI Profile** * **Language** ## Message queue {#message-queue} If you send a message while **Thinking...** or **Running** is shown, a waiting list appears above the input field, under the heading **Queued messages**. Once the current run finishes, queued messages are processed in order starting from the first one. While there's text in the input field, the send button reads **Add to queue**. | Action {.nowrap} | Description | | --- | --- | | **Send now** | Interrupts the run in progress and sends that message immediately | | **Edit** | Edits a queued message. While editing, use **Save** / **Cancel** | | **Delete** | Removes the message from the queue | ## Plan & Todos {#plan-and-todos} You can review the work plan (Plan) and todo list (Todos) that the AI agent created in the session. Open it when the **Plan & Todos** button is shown near the chat input field. ### What's shown {#plan-and-todos-contents} | Item {.nowrap} | Description | | --- | --- | | **Plan** | The Plan saved by the AI agent. Switch the display format with **Rendered** / **Raw**. If none is saved, `No Plan has been saved yet.` is shown. | | **Todos** | Todos for the current session. You can check each item's content and status (`pending` / `in_progress` / `completed`). If none are active, `No todos are currently active.` is shown. | ## Conversation history summary {#conversation-summary} Enter `/` in the input field and select **Summarize conversation history** to summarize the conversation history in the current session. You can continue adding new messages to the queue while the summary runs. Select **Stop generating response** to stop the summary. ## User settings {#user-settings} You can change these from **Settings** > **User Preferences** in the chat input field. | Item | Description | | --- | --- | | **Enter to newline** | When on, Enter inserts a line break and a modifier key+Enter sends. When off, Enter sends | | **Show SQL details** | Shows the SQL body within an Agent message by default | | **Auto-approve Tool Execution** | **Run SQL** (per connection; for BigQuery, you can also set **Size Limit (BigQuery)** in GB), **MCP Tool Execution**, **Connector HTTP Request** | | **Auto-load Agent Context** | **Personal** / **Teamspace** / **Notebook page** (all on by default) | ## Permissions {#permissions} The AI agent's actions are carried out within the user's permission scope. The notebooks it can explore and the connections it can use are also limited to what the user can access. You can configure additional restrictions under **Tool permissions** in the [AI profile](../../workspace/codatum-ai/ai-profile#tool-permissions) (notebooks, connections, connectors, web search / fetch). If you want to confirm every SQL execution, turn off **Run SQL** under **Auto-approve Tool Execution** in user settings. --- --- url: 'https://docs.codatum.com/features/ai-agent/agent-context.md' description: Preparing context that the AI agent loads automatically --- # Agent context You can prepare context that the AI agent loads automatically, using notebooks. For how to use it in chat, see [AI agent](./overview). Agent context doesn't change access permissions. The information it can reference and the operations it can perform are limited to the permission scope of the user and the [AI profile](../../workspace/codatum-ai/ai-profile) in use. ## Agent context folder {#agent-context-folder} Create a folder named `.agent` directly under your personal folder or the root of a teamspace. You can select **New Agent Context folder** from the folder menu in the left sidebar. | Location | Auto-load | | --- | --- | | `.agent` directly under your personal folder | Always loaded when on (the **Personal** user setting) | | `.agent` directly under a teamspace | Loaded while you have a notebook from that teamspace open (the **Teamspace** user setting) | | `.agent` directly under the workspace | Not auto-loaded. Loaded only if specified as context on an [AI profile](../../workspace/codatum-ai/ai-profile) | | `.agent` anywhere else | Not auto-loaded | For a `.agent` folder directly under a personal folder or a teamspace, every notebook within it—including those in subfolders—is loaded. This includes SQL blocks as well as text. ## Agent context page {#agent-context-page} If you add a page named `.agent` within a notebook, its content is loaded while that notebook is open (the **Notebook page** user setting). You can use it to pass things like how to calculate a metric, including through SQL blocks. Use a `.agent` page for assumptions specific to a notebook, and a `.agent` folder for information shared across a person or team. ## AI profile context {#ai-profile-context} The notebooks, folders, and plain text linked to the [AI profile](../../workspace/codatum-ai/ai-profile) selected for the session also become context. If you specify a folder, notebooks in its subfolders are included too. Referencing a context notebook or folder requires the user to have view permission for it. An AI profile that includes a notebook you can't view can't be used. ## Auto-load settings {#auto-load-settings} From **Settings** > **User Preferences** > **Auto-load Agent Context** in the chat input field, you can turn each type on or off. | Item {.nowrap} | Default | Target | | --- | --- | --- | | **Personal** | On | `.agent` directly under your personal folder | | **Teamspace** | On | `.agent` directly under the teamspace the current notebook belongs to | | **Notebook page** | On | The `.agent` page within the current notebook | Context configured on an AI profile isn't covered by these switches. It's always loaded as part of the settings of whichever AI profile is currently selected. You can check which notebooks and pages are currently being auto-loaded from **Context usage** in the chat input field. ## Always-loaded vs. loaded on demand {#load-strategy} You can separate information that's always loaded from information referenced only when needed, based on where you place notebooks and how you link them to an AI profile. | Loading approach | Setting | Behavior | | --- | --- | --- | | Always load personal context | Place notebooks in `.agent` directly under your personal folder, and turn on **Personal** | Loads every notebook in the folder and its subfolders whenever the AI agent runs | | Load teamspace context | Place notebooks in `.agent` directly under a teamspace, and turn on **Teamspace** | Loaded while you have a notebook from that teamspace open | | Load notebook-specific context | Create a `.agent` page in a notebook, and turn on **Notebook page** | Loads the `.agent` page while that notebook is open | | Always load through an AI profile | Set it as the AI profile's plain text, context notebook, or context folder | Loaded every time that AI profile is used | | Reference only when needed | Keep only an index notebook under `.agent`, and put details in a regular folder with a page link to it | The index is auto-loaded, and details are referenced through the link only when a question calls for it | For the agent to reference a detail notebook when needed, the user must be able to view it, and the AI profile's **Notebook access** must be set to **All accessible notebooks**. With **Current notebook only**, details placed outside the current notebook can't be referenced. ## Index notebook {#index-notebook} Notebooks in a `.agent` folder are auto-loaded. Placing a large volume of detailed specifications or past analyses there uses up context on information unrelated to the question at hand. You can put details in regular notebooks and folders, and keep an index notebook under `.agent`. An index should include the following. * What information is available * What kinds of questions it's relevant to * A **link to the page** of the notebook that's the source of truth * Where the notebook is stored * Keywords useful for searching * How to handle cases where information can't be found or a judgment can't be made ::: warning For each reference, set a link to the target page, not just the notebook name. A notebook name or storage location alone doesn't let the AI agent locate a page outside the `.agent` folder directly. Open the target page, copy its URL, and insert it into the index as a link. ::: Here's an example structure. Replace `WORKSPACE_ID` / `NOTEBOOK_ID` / `PAGE_ID` with the actual URL. ```markdown # Agent Context Index ## Common rules * Treat the "KPI Definitions" notebook as the source of truth for metric definitions * If a definition can't be found, don't guess—ask the user * Confirm the target period and time zone before writing SQL ## Knowledge Map ### Sales and orders * Reference: [Sales and order metrics](https://app.codatum.com/workspace/WORKSPACE_ID/notebook/NOTEBOOK_ID/PAGE_ID) * Location: "Data Knowledge" teamspace * When to use: analysis of sales, orders, and cancellations * Search keywords: sales, orders, cancellations, GMV ``` ### Example folder structure {#folder-structure-example} For example, you can arrange the index and source-of-truth notebooks as follows. Folder and notebook names other than `.agent` are up to you and don't affect behavior. Following the GitHub convention of placing one notebook named README in each folder as its entry point makes the intent clear to both people and AI agents. ```text "Data Knowledge" teamspace ├── .agent │ └── README (overall index) ├── Sales and Orders │ ├── README (entry point for this folder) │ └── Order cancellation analysis └── Customers and Churn └── README ``` A bulleted list of links to the target pages, each with a one-line description, is enough for the content of a README. When the hierarchy gets deeper, link from a parent README to the READMEs of its subfolders, so that details can be reached by following READMEs. ```markdown # README * [Sales and Orders Guide](page URL): source of truth for metric definitions and aggregation SQL * [Customers and Churn Guide](page URL): definitions of customer segments and churn rate * If a definition can't be found, don't guess—ask the user ``` Splitting folders by domain, such as sales or customers, keeps them easy to reference from the index and to update. For the idea of managing knowledge as a collection of documents, the Google Cloud article on the [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/) is also a useful reference. ## Configurations to avoid {#avoid} Avoid the following configurations. * Putting every detailed specification or past analysis into a `.agent` folder * Duplicating the same metric definition across multiple contexts * Writing only a summary without indicating the source of truth or a reference * Writing rules with no clear update date or scope of application * Trying to control access permissions or tool execution scope through context Configure access scope and available tools through notebook and teamspace permissions, and through [AI profile](../../workspace/codatum-ai/ai-profile#tool-permissions) tool permissions. --- --- url: 'https://docs.codatum.com/features/ai-assistant/overview.md' description: >- A chat-based AI Assistant for creating SQL and charts and answering questions (deprecated; new provisioning discontinued) --- # AI Assistant (Deprecated) (Optional feature) AI Assistant is a chat-based AI that generates and corrects SQL, creates charts, and answers questions about how to use Codatum, based on natural language instructions. **New provisioning of AI Assistant has ended.** Its successor is [AI agent](../ai-agent/overview). If you're using AI Assistant, follow this page for procedures and specifications. If you're using the AI agent, see [AI agent](../ai-agent/overview). ::: warning This feature is **deprecated** and will be removed in a future release. ::: ::: tip This is an **optional feature**. Depending on your contract, it might not be available. ::: ## Key features * [Sending data to the LLM](#llm-data): How data is handled for training purposes, and what information might be sent to the LLM. * [Availability](#availability): Required permissions and settings. * [Enabling it](#enable): Enable it under **AI feature settings** in workspace settings. * [Opening it](#open): Open it from global nav, a shortcut, or a notebook. * [Roles](#roles): **AI Analyst** / **AI Support**. * [Display modes](#display-modes): Dock sidebar / float / fullscreen. * [Sessions](#sessions): Starting a new session, history, and language/connection settings. * [Notebook integration](#notebook-integration): Applying SQL/charts, fixing errors, and more. * [Relationship with the AI agent](#vs-ai-agent): Differences in how work proceeds and how settings are managed. ## Sending data to the LLM {#llm-data} Only external LLM services that contractually guarantee your input data won't be used for training are used. If you want to use your own API key, you can configure this under **Custom** in [AI profile](../../workspace/codatum-ai/ai-profile#types). AI Assistant might send SQL, the schema of referenced tables, and the messages you enter to the LLM service. Check your organization's AI usage policy before using this feature. ## Availability {#availability} If you're using AI Assistant, the following are required. * Write permission on the notebook. * AI features overall and **AI Assistant** enabled under **AI feature settings** in workspace settings. Depending on your contract, it might not be available. ## Enabling it {#enable} Enabling AI features requires [Workspace Owner](../../workspace/administration/user#workspace-roles) permission. 1. Open [global nav](../../guide/screen-layout) > **Workspace settings** > **AI feature settings**. 2. Turn on AI features overall using the switch at the top of the screen. 3. Turn on **AI Assistant** under **Available AI features**. You can also individually enable the following features on the same screen. | Feature {.nowrap} | Description | | --- | --- | | **AI Assistant** | A chat-based AI that creates SQL and charts and also answers questions | | **AI code completion** | Provides inline SQL completion within a SQL block | | **AI name suggestion** | Automatically suggests names for SQL and charts | If you're using the AI agent, the same switch is labeled **AI Agent**. For setup steps, see [Enabling the AI agent](../ai-agent/overview#enable). ## Opening it {#open} You can open it in any of the following ways. 1. Open **AI Assistant** at the bottom of [global nav](../../guide/screen-layout). If it isn't enabled, go to the enablement screen from **Enable AI Assistant**. 2. Use the **AI Assistant** shortcut (⌘+L / Ctrl+L by default; see [Keyboard shortcuts](../../account/settings/keyboard-shortcut)). 3. On a doc page, type `/` and select **AI Analyst**. 4. From the menu at the top right of a SQL block, select **Open with this SQL**, or **Performance optimization** / **SQL refactoring**. 5. Select **Fix with AI** on a SQL block that has an error. 6. Start a how-to session from **AI support** in the help menu. 7. Select **Summarize**, **Revise and Refine**, or **Translate to** from the menu shown when you select text. ## Roles {#roles} You can switch between the following roles in the chat screen. | Role {.nowrap} | Description | | --- | --- | | **AI Analyst** | Assists with generating and correcting SQL and charts | | **AI Support** | Answers questions about how to use Codatum and provides guidance on its features | ## Display modes {#display-modes} You can switch the display from the header. | Display {.nowrap} | Description | | --- | --- | | **Dock sidebar** | Pins it to the edge of the screen | | **Float** | Displays it floating on screen, and you can move it | | **Fullscreen** | Shows the chat in a larger view | ## Sessions {#sessions} You can perform the following actions from the header. | Action {.nowrap} | Description | | --- | --- | | **Start new session** | Starts a new session | | **Session history** | Lists recent sessions and lets you switch between them | In the chat input field, you can configure the following. | Item {.nowrap} | Description | | --- | --- | | Response language | **The Assistant's response language** | | Connection | In **AI Analyst** mode, the connection the response assumes (this determines the SQL syntax assumed) | Sending a message uses **Request**. From the input field, you can pass context with **Add notebook SQL** / **Add table metadata**. ## Notebook integration {#notebook-integration} While you have a notebook's doc page open, you can apply SQL or charts generated by AI Assistant to the notebook. * Drag the generated SQL, or select **Apply**, to reflect it in the original SQL block. * For charts too, you can **Apply** to the source chart or drag it onto a notebook page. * From a SQL block, you can start a session that includes the target SQL using **Open with this SQL**, **Fix with AI** on an error, and similar. AI Assistant presents suggestions in the chat, and you apply them to the notebook yourself using **Apply** and similar. For autonomous notebook editing, see Agent mode in [AI agent](../ai-agent/overview#operation-modes). ## Relationship with the AI agent {#vs-ai-agent} | Item {.nowrap} | AI Assistant | AI agent | | --- | --- | --- | | Availability | Deprecated. New provisioning has been discontinued | Beta. An [optional feature](../ai-agent/overview) | | How work proceeds | Suggests in chat; you apply the changes | Proceeds autonomously with analysis, notebook editing, and more | | Context | Adding SQL/tables to a message, and similar | `@` mentions, agent context, AI profile, and more | | Model and permission settings | Workspace AI feature settings | [AI profile](../../workspace/codatum-ai/ai-profile) | For details on the successor feature, see [AI agent](../ai-agent/overview). --- --- url: 'https://docs.codatum.com/features/cli/overview.md' description: A CLI for operating Codatum from your terminal --- # Codatum CLI (Beta) `cdm` is a CLI for operating Codatum's features from your terminal, CI, or an AI agent. It doesn't replace everything you can do in the web UI; it mainly covers file-based editing, syncing, and validation of notebooks and the catalog, along with authentication. The quickest way to get started is issuing a token from [Personal Access Tokens](../../account/settings/pat#issue-token) and running `cdm auth login`. For command details, see the [Codatum CLI documentation](https://cli-docs.codatum.com). ::: info This feature is in **beta**. The specification might change without notice. ::: ## Prerequisites {#prerequisites} * See [Requirements](../../reference/requirements#codatum-cli) for supported operating systems. * Not available if the Codatum CLI is disallowed by a [workspace policy](../../workspace/access-and-security/policy#policy-settings). ## Key features * Operating Codatum from your terminal, CI, or an AI agent. * Creating, syncing, and previewing notebooks in markdown form (`.cnb.md`, a local representation of a [notebook](../notebook/overview) in Codatum). * Managing catalog annotations with YAML (such as `.cann.yaml`). * Authenticating with a PAT (issue one under [Personal Access Tokens](../../account/settings/pat#issue-token); for managing them within a workspace, see [Personal Access Tokens](../../workspace/access-and-security/pat#operations)). --- --- url: 'https://docs.codatum.com/workspace/overview.md' description: 'The unit for managing resources, and the settings menu structure' --- # Workspace A workspace is an independent area for each organization that uses Codatum. Resources such as connections, notebooks, reports, catalogs, and workflows belong to a single workspace and can't be referenced from other workspaces. ::: tip You can switch the workspace you're working in, or join a workspace you've been invited to, from the [workspace icon in the global nav](../guide/navigation#workspace-icon). ::: You manage the organization name, country, and organization owners, review, create, and join workspaces in the organization, and manage billing in [Organization settings](./administration/organization). Open it from the avatar icon at the bottom of the global nav > **Organization settings**. Only an organization owner can make these changes. ## Settings You can open workspace settings from the [global nav](../guide/screen-layout) > **Workspace settings**. Each menu provides the following settings. ### Administration {#administration} | Menu {.nowrap} | Content | | --- | --- | | [General](./administration/basic) | Workspace name, icon, allowed domains, and more | | [Users](./administration/user) | Managing members and guests, and assigning workspace roles | | [Groups](./administration/group) | Managing permission-granting units that group users together | | [Teamspaces](./administration/teamspace) | Creating and managing areas where specific members co-manage notebooks | | [Notebook themes](./administration/theme) | Creating and managing notebook themes | ### Access and security {#access-and-security} | Menu {.nowrap} | Content | | --- | --- | | [Workspace policy](./access-and-security/policy) | Restrictions on public links, Codatum CLI, and guest invitations | | [Audit logs](./access-and-security/audit-log) | Records of important operations and system events | | [Public links](../features/notebook/sharing/public-link/overview) | Listing and monitoring active public links | | [API keys](./access-and-security/api-key) | Managing API keys used for signed embeds and more | | [Personal Access Tokens](./access-and-security/pat) | Listing, suspending, and revoking PATs within the workspace | | [MCP](./access-and-security/mcp) | Listing and disconnecting connections from MCP clients | | [Security](./access-and-security/security) | Controlling IP access control and multi-factor authentication | ### Data management {#data-management} | Menu {.nowrap} | Content | | --- | --- | | [Connections](./data-management/connection) | Connection settings to a data warehouse | | [Tags](./data-management/tag) | Tag definitions for tables, columns, queries, reports, and more | ### Codatum AI {#codatum-ai} | Menu {.nowrap} | Content | | --- | --- | | [AI feature settings](../features/ai-agent/overview#enable) | Enabling the [AI agent](../features/ai-agent/overview#enable) / [AI Assistant](../features/ai-assistant/overview#enable), code completion, and more | | [AI profiles](./codatum-ai/ai-profile) | Managing LLM connections and context | | [Agent usage](./codatum-ai/agent-usage) | Checking agent session and token usage | | [Agent Connectors](./codatum-ai/agent-connectors) | Managing the external connectors agents use | ### Subscriptions {#subscriptions} Only an [organization owner](./administration/organization#owners) can change the plan. If you aren't an organization owner, you can't change the plan. A Workspace Owner can view the plan. You manage the billing address, payment method, and invoices in [Billing in organization settings](./administration/organization#billing). Opening **Billing** in workspace settings takes you to **Billing** in organization settings. | Menu {.nowrap} | Content | | --- | --- | | Plan | Checking and changing your current plan. Changing it is limited to organization owners | | Billing | Goes to Billing in organization settings. Organization owners only | | Usage | Checking member counts and usage/limits for each feature | ### Options {#options} | Menu {.nowrap} | Content | | --- | --- | | Integrations | Managing external integrations for workflows (such as Slack). See [Slack](../features/workflow/steps#slack) for setup steps | ### Connector authentication {#connector-authentication} | Menu {.nowrap} | Content | | --- | --- | | [Connector authentication](./codatum-ai/agent-connectors#create-manage) | Per-account agent connector authentication. See the personal-scope authentication section of agent connectors for details | --- --- url: 'https://docs.codatum.com/workspace/administration/organization.md' description: >- Editing the organization name and country, inviting or removing organization owners, creating or joining workspaces in the organization, and managing billing --- # Organization settings Edit the organization name and country, and invite or remove organization owners. You can also review, create, and join workspaces in the organization, and manage billing. An organization is the unit that groups workspaces. Only an organization owner can make these changes. From the avatar icon at the bottom of the [global nav](../../guide/screen-layout) > **Organization settings**, you can open the settings for the organization that the workspace you're working in belongs to. If you aren't an organization owner, this entry point isn't shown. For workspace-level settings such as the workspace name, icon, and allowed domains, see [General](./basic). ## Menus {#menus} The organization name appears above **Organization settings** in the [left sidebar](../../guide/screen-layout). If you own more than one organization, select the organization name to switch to another organization's settings. Use the sidebar to switch between the following screens. | Menu {.nowrap} | Content | | --- | --- | | **General** | Organization ID, organization name, and country | | **Members** | Organization owner list, invitations, and removals | | **Workspaces** | Workspaces that belong to the organization, including creating and joining | | **Billing** | Payment methods, invoices, and billing details | If you opened Organization settings from a workspace, **Back to workspace** at the top of the left sidebar returns you to that workspace's top page. Otherwise, **Back to workspaces** returns you to the [workspace selection screen](../../guide/navigation#workspace-icon). ## Settings {#settings} | Item {.nowrap} | Description | | --- | --- | | Organization ID | The ID that uniquely identifies the organization | | Organization name | The organization's legal name used for contracts and invoices. It can't be empty | | Country | The country used for contracts and billing | ## Organization owners {#owners} An organization owner can edit organization settings and invite or remove other organization owners. An organization owner can also manage **Billing** in organization settings and change the plan in workspace settings. This role is separate from workspace roles. The last organization owner can't be removed. If you remove yourself, you can no longer open organization settings. ## Invitations {#invite} Use **Send invitation** to invite an organization owner by email address. The role isn't granted when you send the invitation. The recipient becomes an organization owner after they accept. The following constraints apply. * Invitations expire 7 days after creation ([Fixed limits and constraints](../../reference/limits#fixed-limits)). * You can't invite an email address that already belongs to the organization as an owner. * You can't send duplicate invitations to the same email address. ### Pending invitations {#pending-invitations} You can review invitations that haven't been accepted under **Pending invitations**. | Display / action {.nowrap} | Description | | --- | --- | | **Pending Invite** | Not yet accepted, and still within the expiration period | | **Invite expired** | An invitation past its expiration | | **Resend** | Resends the invitation email and extends the expiration to 7 days from the resend time | | **Delete** | Cancels the invitation | ## Flow for the invitee {#invitee-flow} To join as an organization owner after being invited, the invitee needs a Codatum account. If they don't have one, they first need to create an account via [Sign up](../../account/signup). After creating an account, or if they already have one, they select **Join** or **Decline** in one of the following places. * The link in the invitation email * The [workspace selection screen](../../guide/navigation#workspace-icon) The following constraints apply. * The invited email address must match the account's email address. * Selecting **Join** makes them an organization owner. * Selecting **Decline** deletes the invitation. ## Workspaces {#workspaces} You can review the workspaces that belong to this organization. For a workspace you have joined, select **Open** to go to its top page. For a workspace you haven't joined, select **Join** to add yourself as a Workspace Owner. You can't view the content of workspaces you haven't joined. Depending on your contract, you might not be able to create a workspace from organization settings. In that case, contact Codatum support. | Display / action {.nowrap} | Description | | --- | --- | | **Create workspace** | Adds a workspace to this organization. You set the icon, workspace name, and allowed domain, then continue to initial setup such as inviting members. Depending on your contract, this action might not be shown. | | Workspace | The workspace name. | | **Active** / **Locked** | The workspace status. | | Plan | The workspace plan. If the workspace is in a trial, the remaining days are also shown. If you have joined the workspace, you can open [Plans](../overview#subscriptions) in workspace settings. | | Members | The number of members in the workspace. | | Created | The date the workspace was created. | | **Joined** / **Not a member** | Whether you have joined the workspace. | | **Open** | Opens the top page of a workspace you have joined. | | **Join** | Adds you to a workspace you haven't joined, as a Workspace Owner. | ## Billing {#billing} Payment methods, invoices, and billing details are shared across all workspaces in the organization. Invoice history shows the workspace name for each invoice. To view or change a plan, use [Plans](../overview#subscriptions) in workspace settings. Opening **Billing** in workspace settings takes you to **Billing** in organization settings. --- --- url: 'https://docs.codatum.com/workspace/administration/basic.md' description: >- Managing workspace name, icon, and allowed domains, and viewing organization details --- # General Manage the workspace's name, icon, and allowed domains, and view its organization details. Only a Workspace Owner can change workspace settings or delete the workspace ([Workspace permissions](../../permissions/workspace)). Open this from the [global nav](../../guide/screen-layout) > **Workspace settings** > **General**. ## Settings {#settings} | Item {.nowrap} | Description | | --- | --- | | Workspace ID | The ID that uniquely identifies the workspace | | Icon | The icon shown in the [global nav](../../guide/screen-layout) | | Workspace name | The workspace name shown when switching workspaces and elsewhere | | Country | The country used for contracts and billing. Change it in [Organization settings](./organization#settings) | | Organization name | The organization's legal name used for contracts and invoices. Change it in [Organization settings](./organization#settings) | | Allowed domains | See [Invitations and joining](./invite#allowed-domains) for details | ## Danger zone {#danger-zone} You can **delete the workspace**. Deleting it also deletes all related data, including notebooks, folders, and comments. Depending on your payment method, you might not be able to delete it. If that happens, contact Codatum support. --- --- url: 'https://docs.codatum.com/workspace/administration/user.md' description: 'Members / guests, and workspace roles' --- # Users A user is an [account](../../account/overview#account-and-user) that belongs to a workspace. Users are classified as members or guests, and every user is assigned exactly one workspace role for each workspace they belong to. You can manage users within a workspace from [global nav](../../guide/screen-layout) > **Workspace settings** > **Users**. For permissions by workspace role, see [Workspace permissions](../../permissions/workspace); for inviting users, see [Invitations and joining](./invite). ## Members and guests {#member-and-guest} | Category {.nowrap} | Workspace roles included {.nowrap} | Summary | | --- | --- | --- | | Member | Workspace Owner, Workspace Editor, Workspace Viewer | Users who use the workspace's main features | | Guest | Workspace Guest | Users who can only access limited resources, such as explicitly shared reports | * **User** = member + guest (every account that belongs to the workspace) * **Member** = user excluding guests Guests can't belong to a group. Also, **Workspace settings** in the [global nav](../../guide/screen-layout) isn't shown to guests. ## Workspace roles {#workspace-roles} Every user is always assigned exactly one workspace role. | Role {.nowrap} | Summary | | --- | --- | | Workspace Owner | Has full administrative permissions for the workspace, including user management | | Workspace Editor | Can create and edit content such as notebooks and connections. Can't invite users or change workspace settings | | Workspace Viewer | Can view content but can't edit it | | Workspace Guest | Can only view limited resources, such as shared reports | For permissions by role, see [Permissions overview](../../permissions/overview) and [Workspace permissions](../../permissions/workspace). ## Deleting a user {#delete-user} A Workspace Owner can remove a user from the workspace from the **Users** screen. When removed, that user's [Private](../../permissions/resources/notebook#scope-private) folder (including the notebooks and folders within it) is deleted. Notebooks in other access scopes, such as the workspace or a teamspace, remain intact. --- --- url: 'https://docs.codatum.com/workspace/administration/group.md' description: A unit for granting permissions to a group of users --- # Group (Optional feature) A group is a unit for managing multiple users together and granting them access to resources in bulk. Manage groups from [global nav](../../guide/screen-layout) > **Workspace settings** > **Groups**. A user can belong to multiple groups. Permissions granted to a group are inherited by its [members](./user#member-and-guest) and its [Group Owners](#group-owner). For how permission evaluation works, see [Permissions overview](../../permissions/overview). ::: tip This is an **optional feature**. Depending on your contract, it might not be available. ::: ## Creating and managing 1. Open [global nav](../../guide/screen-layout) > **Workspace settings** > **Groups**. 2. From **New group**, specify the **group name** and **members**. 3. Select **Edit** on a row in the list to open **Group settings**. **Group settings** lets you check and manage the following. * **Group name** / **icon** * **Group Owners** * **Group members** * **Granted permissions** (connection / teamspace / notebook / report) You can also add members from the following entry points. * **Add to group** in [global nav](../../guide/screen-layout) > **Workspace settings** > **Users** * Specifying a group during email invitations in [Invitations and joining](./invite#email-invite) ## Required roles {#required-roles} For the roles required to create and manage groups, and which resource roles can be granted, see [Group permissions](../../permissions/resources/group). ## Group Owner {#group-owner} A **Group Owner** can edit the target group and manage its members even without being a Workspace Owner. Permissions granted to a group are also granted to its Group Owners. * A group can have up to 3 owners ([Fixed limits and constraints](../../reference/limits#fixed-limits)). * A group can also operate without any owners (zero is allowed). ## Granting permissions Permissions are granted to a group mainly through the sharing and permission settings of each resource. The typical label when selecting a target is **Add group or member**. Examples of resources you can grant permissions on: * [Connection](../../permissions/resources/connection) * [Teamspace](../../permissions/resources/teamspace) * [Notebook](../../permissions/resources/notebook) * [Report](../../permissions/resources/report) **Granted permissions** in the group settings lets you check permissions that have already been granted. For connections and teamspaces, you can sometimes change the role from here too (only a Workspace Owner can make the change). ## Automatic assignment by allowed domain {#auto-assign-by-domain} Automatically assigning a group by email domain is set up not on the group screen, but under [global nav](../../guide/screen-layout) > **Workspace settings** > [**General**](./basic) > **Allowed domains**. You can specify a **default group** for each domain. For the join flow and constraints, see [Invitations and joining](./invite#allowed-domains). ## Constraints * A [Workspace Guest](./user#member-and-guest) can't belong to any group. * You can check the maximum number of groups from global nav > **Workspace settings** > **Usage** ([Fixed limits and constraints](../../reference/limits#plan-limits)). --- --- url: 'https://docs.codatum.com/workspace/administration/invite.md' description: >- Email invitations, invite links, allowed domains, and guest invitations from reports --- # Invitations and joining How to invite and join users to a workspace. Only a Workspace Owner can configure email invitations, invite links, and allowed domains ([Workspace permissions](../../permissions/workspace)). Unless disabled by the [workspace policy](../access-and-security/policy#policy-settings), a Workspace Editor can also invite guests from the report screen. Here's a comparison of the ways to join. | Method {.nowrap} | Who performs it | Role/group on joining {.nowrap} | How to join {.nowrap} | | --- | --- | --- | --- | | [Email invitation](#email-invite) | Workspace Owner | Specified at invitation time | Join from the [workspace selection screen](../../guide/navigation#workspace-icon) | | [Allowed domain](#allowed-domains) | The joining user | Specified at setup time | Join from the [workspace selection screen](../../guide/navigation#workspace-icon) | | [Invite link](#invite-link) | The user who received the link | Editor (fixed), no group | Join by opening the link | | [Guest invitation from a report](#guest-invite-from-report) | A user with report sharing permission | Guest, no group | Join from the [workspace selection screen](../../guide/navigation#workspace-icon) | ## Flow for the invitee {#invitee-flow} To join a workspace after being invited, the invitee needs a Codatum account. If they don't have one, they first need to create an account via [Sign up](../../account/signup). After creating an account, or if they already have one, they check and accept the invitation from the [workspace selection screen](../../guide/navigation#workspace-icon). An [invite link](#invite-link) lets them join directly, without going through the selection screen. If they aren't logged in, they log in or sign up, then return to the original link to join. For organization owner invitations, see [Organization settings](./organization#invitee-flow). ## Email invitation {#email-invite} Open [global nav](../../guide/screen-layout) > **Workspace settings** > **Users**, then select **Invite users** > **Send invitation email**. Only a Workspace Owner can send invitation emails. You can specify the following. * **Email address** * **Workspace role** * **Group** The following constraints apply. * Invitations expire 7 days after creation ([Fixed limits and constraints](../../reference/limits#fixed-limits)). * You can't specify a group if you select Guest ([Members and guests](./user#member-and-guest)). * You can't invite an email address that already belongs to the workspace. * You can't send duplicate invitations to the same email address. The recipient of the invitation email checks the invitation on the [workspace selection screen](../../guide/navigation#workspace-icon) and selects **Join** or **Decline** (see [Flow for the invitee](#invitee-flow)). * The invited email address must match the account's email address. * Selecting **Join** applies the role and group specified at invitation time. * Selecting **Decline** deletes the invitation. ### Pending invitations {#pending-invitations} You can check unaccepted invitations from **Pending invitations** in [global nav](../../guide/screen-layout) > **Workspace settings** > **Users**. | Display / action {.nowrap} | Content | | --- | --- | | **Pending Invite** | Within the expiration period and not yet accepted | | **Invite expired** | Past the expiration date | | **Resend** | Resends the invitation email and extends the expiration to 7 days from the resend time | | **Delete** | Cancels the invitation | ## Allowed domains {#allowed-domains} Configure this under [global nav](../../guide/screen-layout) > **Workspace settings** > [**General**](./basic) > **Allowed domains**. Only a Workspace Owner can change this. An account whose email address matches an allowed domain can join that workspace. Joining isn't automatic — they need to select **Join** from the list on the [workspace selection screen](../../guide/navigation#workspace-icon) (see [Flow for the invitee](#invitee-flow)). You can set the following for each domain. * **Default role** * **Default groups** The following constraints apply to domains you can add. * You choose from the email domains of existing members. * Free email domains can't be added. For automatic group assignment via allowed domains, also see [Group](./group#auto-assign-by-domain). ## Invite link {#invite-link} Open [global nav](../../guide/screen-layout) > **Workspace settings** > **Users**, then use **Invite link** within **Invite users**. Only a Workspace Owner can view, generate, and regenerate the invite link. * Share the generated link with the person you want to invite. * What happens when they open the link depends on their login state: * **Logged in**: they join the workspace immediately. * **Not logged in**: after logging in or [signing up](../../account/signup), they join the workspace (see [Flow for the invitee](#invitee-flow)). * A user who joins via an invite link is assigned **Workspace Editor**. The link has the following specifications. * Regenerating it issues a new link, and the old one stops working. * The invite link itself has no expiration date. * There's no way to disable it. If you no longer need it, **regenerate** it. ## Guest invitation from a report {#guest-invite-from-report} Open **Share** on the report screen, select **Share report**, and specify an email address in **Invite guest by email**. You can invite a user who hasn't joined the workspace as a [guest](./user#member-and-guest). The recipient of the invitation email checks the invitation on the [workspace selection screen](../../guide/navigation#workspace-icon) and selects **Join** or **Decline** (see [Flow for the invitee](#invitee-flow)). * Accepting the invitation adds them to the workspace as a Workspace Guest, and grants Report Viewer on the target report. * Inviting a guest requires the same permission as changing report permissions. For details, see [Report permissions](../../permissions/resources/report#guest-sharing). * If the [workspace policy](../access-and-security/policy#policy-settings) disables guest invitations to reports by Workspace Editors, only the Workspace Owner can invite guests. * You can check or cancel guests you've invited from **Pending guest invitations** in the same panel. To share with a user who has already joined the workspace, use the report's sharing settings instead. For a feature overview, see [Report](../../features/notebook/sharing/report/overview). ## When multiple join methods overlap {#overlapping-invites} If an email invitation is pending and the user joins via an allowed domain or an invite link instead, the role from the join method they used takes priority. * Joining via an allowed domain: the domain's default role applies (the role specified in the invitation isn't used). * Joining via an invite link: Workspace Editor applies (the role specified in the invitation isn't used). Even if a guest invitation from a report is pending, joining via an invite link makes the user a Workspace Editor. If you want them to join as a guest, have them accept via **Join** on the email invitation. --- --- url: 'https://docs.codatum.com/workspace/administration/teamspace.md' description: An area for specific members to co-manage notebooks --- # Teamspace (Optional feature) A teamspace is a notebook folder with permission management. Only users and groups granted a permission can view the notebooks within that teamspace. Use it when you want to separate access by team rather than publishing to the entire workspace. Create and manage teamspaces from [global nav](../../guide/screen-layout) > **Workspace settings** > **Teamspaces**. In the [left sidebar](../../guide/screen-layout) of the notebook screen, each teamspace name is shown as a root folder. For the overall folder layout, see [Folder](../../features/notebook/folder). ::: tip This is an **optional feature**. Depending on your contract, it might not be available. ::: ## Creating and managing 1. Open [global nav](../../guide/screen-layout) > **Workspace settings** > **Teamspaces**. 2. Select **New teamspace**. 3. Enter a **teamspace name** (you can also set an icon). 4. To add members at creation time, specify users or groups and their roles under **Permissions**, then select **Create**. To grant permissions later, add them from **Teamspace settings** after creation. The creator becomes the Teamspace Owner. The roles that can be granted at creation are Teamspace Editor / Teamspace Viewer (owners are managed from settings after creation). The list shows **Name** / **Permissions** / **Owner**. Select **Edit** from the row menu to open **Teamspace settings**, and use **Delete** to delete the teamspace. **Teamspace settings** lets you check and manage the following. * **Teamspace name** / icon * **Teamspace Owners** * **Permissions** (granting roles to users and groups) * **Teamspace change logs** (audit log. Viewable by the Workspace Owner) ## Required roles {#required-roles} For the roles required to create and manage teamspaces, and which resource roles can be granted, see [Teamspace permissions](../../permissions/resources/teamspace). ## Teamspace Owner {#teamspace-owner} A **Teamspace Owner** can edit the target teamspace and manage its permissions even without being a Workspace Owner. A Teamspace Owner is also granted the permissions of a Teamspace Editor. * A teamspace can have up to 3 owners ([Fixed limits and constraints](../../reference/limits#fixed-limits)). * A teamspace can also operate without any owners (zero is allowed). The Workspace Owner can always manage it. The typical label when selecting who to grant permissions to is **Add group or member** (or **Add member** if the group feature is disabled). For the roles required to view, edit, share, and publish notebooks within a teamspace, see [Notebook](../../permissions/resources/notebook#scope-teamspace). ## Constraints * You can check the maximum number of teamspaces from global nav > **Workspace settings** > **Usage** ([Fixed limits and constraints](../../reference/limits#plan-limits)). * Deleting a teamspace also deletes all the notebooks and folders under it. This operation can't be undone. --- --- url: 'https://docs.codatum.com/workspace/administration/theme.md' description: The visual theme for a notebook's appearance --- # Notebook theme (Optional feature) A notebook theme lets you customize a notebook's fonts and colors. It's reflected in chart colors and in the text, background, and borders across the page. ::: tip This is an **optional feature**. Depending on your contract, it might not be available. ::: ## Settings {#settings} A theme has the following settings. ### Common | Item {.nowrap} | Description | | --- | --- | | **Theme name** | The name of the theme | | **Font family** | If you specify multiple fonts, the ones listed first are prioritized | | **Base font size** | The size of text, inputs, buttons, and other elements throughout the page is based on this size. If a chart's **Advanced settings** specify a **Base font size**, the chart setting takes priority. | ### Light theme / Dark theme You can set the following separately for light and dark. * **Chart color** * **Status color** * **Primary color** * **Focus color** * **Link color** * **Background color** * **Text color** * **Border color** You can copy settings such as chart colors between light and dark (excluding background, text, and border colors). ## Creating and applying {#create-apply} ### Creating 1. Open [global nav](../../guide/screen-layout) > **Workspace settings** > **Notebook themes**. 2. Configure it from **Create notebook theme**. Creating and editing requires [Workspace Owner](./user#workspace-roles) permission. ### Applying From the notebook screen's menu > **Notebook theme**, choose the theme to apply to the notebook. Notebook edit permission is required. For operations on the target notebook, see [Notebook](../../features/notebook/overview). The default theme is applied to new notebooks. It doesn't affect existing notebooks. ## Scope of effect {#scope} When you change an existing notebook theme, the change is reflected in notebooks that use that theme. The theme at the time of publishing is reflected in [reports](../../features/notebook/sharing/report/overview), [public links](../../features/notebook/sharing/public-link/overview), and [signed embeds](../../features/notebook/sharing/signed-embed/overview). To apply theme changes to published resources, republish them (for example, with **Publish changes**). --- --- url: 'https://docs.codatum.com/workspace/access-and-security/policy.md' description: 'Policies for public links, Codatum CLI, and guest invitations' --- # Workspace policy (Optional feature) From [global nav](../../guide/screen-layout) > **Workspace settings** > **Workspace policy**, you can set workspace-wide restrictions. Only a Workspace Owner can change these ([Workspace permissions](../../permissions/workspace)). ::: tip This is an **optional feature**. Depending on your contract, it might not be available. ::: ## Settings {#policy-settings} | Item | Description | | --- | --- | | Disable public link creation and updates for this workspace | Disables creating and updating (republishing) public links. Existing public links aren't deleted | | Disable Codatum CLI for this workspace | Existing PATs aren't deleted, but creating new ones and using issued PATs is disabled. The [Codatum CLI](../../features/cli/overview) also becomes unusable | | Disable guest invitations to reports by editors in this workspace | Doesn't affect guests already invited; only disables new guest invitations. When enabled, only a Workspace Owner can invite guests | The guest invitation item is shown only if the report feature is enabled for the workspace. For the guest invitation steps, see [Invitations and joining](../administration/invite#guest-invite-from-report). --- --- url: 'https://docs.codatum.com/workspace/access-and-security/audit-log.md' description: Records of important operations and system events --- # Audit logs (Optional feature) Records important user operations and system events. You can view it from [global nav](../../guide/screen-layout) > **Workspace settings** > **Audit logs**, and from each resource's **Change logs**. Only a Workspace Owner can view it ([Workspace permissions](../../permissions/workspace)). ::: tip This is an **optional feature**. Depending on your contract, it might not be available. ::: ## Information shown on screen The audit log screen has the following columns. | Column {.nowrap} | Content | | --- | --- | | Time | When the operation occurred | | Status | **Success** / **Error** / **Deny** | | IP | The IP address the operation came from (only on the workspace settings audit log screen; not shown in each resource's **Change logs**) | | Log | The operation described in natural-language text, including the actor (user, API key, and so on) and the target resource | * Log text is recorded in English. * Email addresses are partially masked. * Content such as notebook body text isn't recorded. Metadata such as resource IDs and names is recorded. ## Search {#search} 1. Open [global nav](../../guide/screen-layout) > **Workspace settings** > **Audit logs**. 2. In the search field, choose a user, group, or API key, or enter a keyword. 3. Select **Search**. * There's no filtering by category or operation type. * Keywords do a partial match against the log text. Prefix a word with `-` to exclude logs containing it. * Select **Refresh logs** to get the latest list. ## Relationship with change logs {#change-history} You can view workspace-wide logs from **Audit logs**. Resource-scoped logs are available from the paths in the following table as **Change logs** (on some screens, **Logs** or **History**). | Path {.nowrap} | Scope | | --- | --- | | Workspace settings > **General** > **Change logs** | Changes to the workspace itself | | Workspace settings > **Users** > **Change logs** | Changes related to users and invitations | | Workspace settings > **Groups** > group edit screen > **Change logs** | Changes to that group | | Workspace settings > **Teamspaces** > teamspace edit screen > **Change logs** | Changes to that teamspace | | Workspace settings > **API Keys** > **Change logs** | API key management operations | | Workspace settings > **Personal Access Tokens** > **Change logs** | PAT management operations | | Workspace settings > **Connections** > permission settings screen > **Change logs** | Permission changes for that connection | | Notebook **Share** > **Public link** > **Change logs** | Changes to that public link | | Notebook **Share** > additional permissions **Change logs** | Changes to that notebook's additional permissions | | Report **Report settings** > **Logs** | Changes to that report | **Using** an API key or PAT (token use) is included in the workspace-wide audit log. It's excluded from each key's management **Change logs**. ## Recorded operations {#recorded-operations} Examples of operations recorded for audit purposes. | Resource {.nowrap} | Example operations | | --- | --- | | Workspace | Creation, renaming, deletion, setting changes | | Users / invitations | Sending, deleting, resending, accepting, and declining invitations; joining via invite link or allowed domain; role changes; user removal; adding, changing, and removing permissions | | Group | Creation, renaming, deletion, icon changes, member joining and leaving, adding and removing owners, adding, changing, and removing permissions | | API key | Creation, renaming, deletion, retrieving/adding/removing secrets, usage | | PAT | Creation, updates, revocation, suspension, unsuspension, usage | | Connection | Creation, deletion, access level changes, adding and removing owners, running SQL, getting results, exporting, cancelling | | Teamspace / folder | Creation, renaming, deletion, moving, owner changes | | Notebook | Creation, deletion, renaming, moving, duplicating, restoring, opening, updates, additional permission changes | | Notebook version | Creation, renaming, deletion, opening | | Report | Publishing, publishing changes, deletion, sharing, guest invitations, viewing | | Public link | Publishing, publishing changes, deletion | | Signed embed | Publishing, publishing changes, deletion, updating allowed origins, adding and removing API keys and parameters, issuing tokens | | Catalog-related | Creating, updating, and deleting tags, updating table annotations | | Workflow | Creation, duplication, updates, deletion, running and cancelling jobs | | Notebook theme | Adding, updating, and deleting | ## Retention and export * The retention period is 1 year ([Fixed limits and constraints](../../reference/limits#fixed-limits)). * There's currently no export feature on the screen. If you need to export data, contact Codatum support. --- --- url: 'https://docs.codatum.com/workspace/access-and-security/api-key.md' description: API keys tied to a workspace --- # API key An API key is tied to a workspace and is used to authenticate [signed embeds](../../features/notebook/sharing/signed-embed/overview). Manage API keys from [global nav](../../guide/screen-layout) > **Workspace settings** > **API keys**. Only a Workspace Owner can create a key or retrieve a secret ([Workspace permissions](../../permissions/workspace)). ## What you can manage * **New API Key** creates a key, and you can manage its name, API key, and API secret. * The list shows **Name** / **API Key** / **API Secret** / **Last used (Created)**. * To rotate keys, you can issue multiple secret versions for a single API key (**Add secret**). * You can **Copy secret**, delete a secret, **Rename** or delete a key, and view its **Usage logs** / **Change logs**. API secrets are only handled server-side. If you lose one, add a new secret version or recreate the API key. Creating and deleting API keys, retrieving, creating, and deleting secrets, and using a key are all recorded in the [audit log](./audit-log). ## Issuing a token For issuing tokens for signed embeds, see [Integration steps](../../features/notebook/sharing/signed-embed/integration#issue-token). --- --- url: 'https://docs.codatum.com/workspace/access-and-security/pat.md' description: List and management of personal access tokens within a workspace --- # Personal Access Tokens (Beta) A PAT (personal access token) is a credential for operating Codatum from the [Codatum CLI](../../features/cli/overview). For how each user issues and edits their own tokens, see the account's [Personal Access Tokens](../../account/settings/pat) page. From [global nav](../../guide/screen-layout) > **Workspace settings** > **Personal Access Tokens**, you can list and manage PATs issued within the workspace. ::: info This feature is in **beta**. The specification might change without notice. ::: ## Prerequisites * The menu is shown and usable only if the [workspace policy](./policy#policy-settings) doesn't disable Codatum CLI use. * [Guests](../administration/user#member-and-guest) can't use PATs. * **Suspend** / **Resume** / **Revoke** can be performed by a Workspace Owner ([Workspace permissions](../../permissions/workspace)). ## List | Column {.nowrap} | Description | | --- | --- | | Issuer | The user who issued the token | | Name (token) | The token name and a masked display with a prefix | | Permission restriction | **Configured** if a permission boundary is set; otherwise `-` | | Last used | The last-used time (**Unused** if never used) | | Expires | The token's expiration date | | Status | **Active** / **Suspended** / **Revoked** / **Expired** | By default, revoked and expired tokens are hidden. Turn on **Show revoked and expired** to include them in the list. You can search by token name or issuer. ## Operations {#operations} | Operation {.nowrap} | Description | | --- | --- | | View permissions | Check the grants of a token that has a permission restriction configured | | Suspend | Temporarily blocks authentication for an active token, until resumed | | Resume | Re-enables authentication for a suspended token | | Revoke | Immediately invalidates the token. This can't be undone | You can check the audit log for PAT changes from **Change logs**. For an overview of the audit log, see [Audit logs](./audit-log). ## Relationship with account settings | Location | What you can do | | --- | --- | | [Personal Access Tokens in account settings](../../account/settings/pat#issue-token) | Create, update, suspend, and revoke tokens you issue yourself | | Personal Access Tokens in workspace settings (this page) | List tokens issued within the workspace, and **Suspend** / **Resume** / **Revoke** / **View permissions** | A permission boundary is a mechanism that caps the token at the issuing account's user permissions, then further narrows it to a scope of connections / notebooks / tags. For an overview, see [Permissions overview](../../permissions/overview#credentials). --- --- url: 'https://docs.codatum.com/workspace/access-and-security/mcp.md' description: >- Connecting MCP clients to Codatum, and managing scopes, available tools, and connections --- # MCP (Preview) Codatum provides an MCP (Model Context Protocol) server. By connecting MCP clients such as Claude and Cursor, you can run the [AI agent](../../features/ai-agent/overview) from those clients. ::: info This feature is in **preview**. To request access, contact Codatum support. ::: AI agent runs use the permissions of the connected user. From [global nav](../../guide/screen-layout) > **Workspace settings** > **MCP**, you can check the MCP URL and manage connections. ## Connecting {#connect} 1. In **Workspace settings** > **MCP**, copy the **MCP URL**. 2. Add the MCP URL to your MCP client. For how to add it, see the documentation of your MCP client. 3. The MCP client opens the Codatum authorization page in your browser. Sign in and select the **Workspace** to connect. 4. Review the scopes under **Permissions requested** and select **Authorize**. After approval, the connection appears in the connection list. A connection is created for each combination of user and workspace. To connect to another workspace, authorize again. Authorization uses OAuth (authorization code flow with PKCE). No client pre-registration is required; Dynamic Client Registration and Client ID Metadata Documents are supported. ## Scopes {#scopes} Scopes define the operations the connected MCP client can perform. The authorization page shows the requested scopes, and only the approved scopes are granted to the connection. The `catalog:read`, `saved-query:read`, and `support:read` scopes are available when MCP Gateway is enabled for your workspace. | Scope {.nowrap} | Description | | --- | --- | | `agent:execute` | Create and run AI agent sessions in the connected workspace and read their results. | | `catalog:read` | Search and read connections, schemas, tables, tags, and table annotations in the connected workspace. | | `saved-query:read` | Search and read saved queries. | | `support:read` | Read Codatum file format references. | ## Available tools {#tools} The connected MCP client can use the following tools based on the authorized scopes. | Tool {.nowrap} | Required scope {.nowrap} | Description | | --- | --- | --- | | `list_ai_profiles` | `agent:execute` | Lists the available [AI profiles](../codatum-ai/ai-profile). | | `send_message` | `agent:execute` | Sends a message to an agent session. If the session ID is omitted, a new session is created. | | `get_agent_session` | `agent:execute` | Gets the session status, messages, pending approvals, and the session URL in Codatum. | | `respond_to_approval` | `agent:execute` | Approves or rejects a pending tool execution. | | `abort_agent_session` | `agent:execute` | Aborts a running session. | | `list_connections` | `catalog:read` | Lists the available connections. | | `list_catalog_schemas` | `catalog:read` | Lists schemas registered in the data catalog. | | `search_catalog_tables` | `catalog:read` | Searches tables by keywords, schemas, tags, and other conditions. | | `list_catalog_tags` | `catalog:read` | Lists table and column tags registered in the data catalog. | | `list_catalog_table_annotations` | `catalog:read` | Lists table and column annotations in a schema. | | `list_catalog_unreferenced_tags` | `catalog:read` | Lists tags that are not assigned to any table or column. | | `search_saved_queries` | `saved-query:read` | Searches saved queries by keywords, connections, folders, and other conditions. | | `get_saved_query` | `saved-query:read` | Gets saved query details. | | `read_file_format` | `support:read` | Reads Codatum file format references. | When an agent action is pending approval (for example, an operation with **Auto-approve Tool Execution** turned off in [user settings](../../features/ai-agent/overview#user-settings)), you can approve or reject it from the MCP client. You can also open the session in Codatum. ## Connection list {#connections} Each user can view their own connections. Switching to **All connections** can be performed by a Workspace Owner ([Workspace permissions](../../permissions/workspace)). | Column {.nowrap} | Description | | --- | --- | | Client | The name of the connected MCP client | | Connected by | The user who made the connection (shown only in **All connections**) | | Scopes | The operations the connection is allowed to perform ([Scopes](#scopes)) | | Connected | When the authorization was approved | | Last used | When the connection was last used | ## Disconnecting {#disconnect} Select **Disconnect** to revoke the authorization. The client can no longer access the workspace and must be authorized again to reconnect. You can disconnect your own connections. A Workspace Owner can disconnect any connection in the workspace. --- --- url: 'https://docs.codatum.com/workspace/access-and-security/security.md' description: Controlling IP access control and multi-factor authentication --- # Security (Beta) (Optional feature) Workspace-wide access control. You can configure it from [global nav](../../guide/screen-layout) > **Workspace settings** > **Security**. Only a Workspace Owner can change it ([Workspace permissions](../../permissions/workspace)). You can configure [IP access control](#ip-access-control) and [multi-factor authentication control](#mfa-control). For an individual account's own login methods (password, Google login, MFA registration), see [Login and security](../../account/settings/login#account-mfa). ::: info This feature is in **beta**. The specification might change without notice. ::: ::: tip This is an **optional feature**. Depending on your contract, it might not be available. ::: ## IP access control {#ip-access-control} Limits workspace access to allowed IP addresses or CIDR ranges only. ### Setup {#ip-access-control-setup} 1. Open [global nav](../../guide/screen-layout) > **Workspace settings** > **Security**. 2. Turn on **Enable IP Access control**. 3. To apply this to guests as well, turn on **Include guests**. 4. Enter the allowed IPs in **Allowed IP address**. ### Supported formats {#ip-address-formats} **Allowed IP address** accepts the following formats: * A single IP address (for example, `203.0.113.15`) * CIDR notation (for example, `192.168.1.0/24`) * Both IPv4 and IPv6 * Multiple IP addresses or ranges When you enter values, your current IP address appears as a suggestion. ### Scope {#ip-access-control-scope} * Access to resources in the workspace while signed in is in scope. [Reports](../../features/notebook/sharing/report/overview) are also in scope. * Turning on **Include guests** also applies this to [guests](../administration/user#member-and-guest). * [Public links](../../features/notebook/sharing/public-link/overview) and [signed embeds](../../features/notebook/sharing/signed-embed/overview) aren't affected. ### Notes {#ip-access-control-notes} * Changed settings apply immediately to users who newly sign in. For users who are already signed in, it can take some time to take effect. * You must be accessing from at least one of the allowed IPs when you save. ### If you lose access {#ip-access-control-lockout} If incorrect IP restrictions lock you out, contact Codatum support. ## Multi-factor authentication control {#mfa-control} Requires multi-factor authentication for password logins. ### Setup {#mfa-control-setup} 1. Open [global nav](../../guide/screen-layout) > **Workspace settings** > **Security**. 2. Turn on **Require Multi-factor authentication**. 3. To apply this to guests as well, turn on **Include guests**. ### Specifications {#mfa-control-spec} * Password login is in scope. Google login isn't affected. * Turning on **Include guests** also applies this to [guests](../administration/user#member-and-guest). * For MFA registration on the account side, see [Login and security](../../account/settings/login#account-mfa). --- --- url: 'https://docs.codatum.com/workspace/data-management/connection.md' description: >- Connection settings to a data warehouse. See the Connection feature for details --- # Connection See [Connection](../../features/connection/overview) for details. --- --- url: 'https://docs.codatum.com/workspace/data-management/tag.md' description: Tag definitions and types within a workspace --- # Tag A tag is a label you attach to a resource to classify and search for it. The [**definition**](#tag-definition) of a tag is managed in workspace settings, and it's [**assigned**](#tag-assignment) from each resource's screen. ## Tag types {#tag-types} The tags screen in workspace settings has the following tabs. | Tab {.nowrap} | Assigned to | | --- | --- | | **Table tag** | Catalog tables | | **Query tag** | Saved queries | | **Column tag** | Table or query columns | | **Report tag** | Reports | ## Tag definition {#tag-definition} 1. Open [global nav](../../guide/screen-layout) > **Workspace settings** > **Tags**. 2. Select a type tab, then select **New tag**. 3. Enter a **name**, **color**, and **description**, check the **preview**, and save. Creating, editing, and deleting tag definitions can be done by a Workspace Owner or Workspace Editor. For details, see [Workspace permissions](../../permissions/workspace). ## Tag assignment {#tag-assignment} Assignment is done from the target resource's screen. You can only assign tags whose type matches the resource. | Assigned to {.nowrap} | See | | --- | --- | | Tables / columns | [Annotation](../../features/catalog/annotation) | | Saved queries | [Query](../../features/saved-query/overview) | | Reports | [Report](../../features/notebook/sharing/report/overview) | ## Search Assigned tags can be used to filter each list and in [Quick search](../../features/quick-search/overview). --- --- url: 'https://docs.codatum.com/workspace/codatum-ai/ai-profile.md' description: 'Settings for the model, permissions, and context the AI agent uses' --- # AI profile An AI profile is a setting that bundles the connection method, permissions, and fixed context for the LLM the [AI agent](../../features/ai-agent/overview) uses. It's also used by LLM actions in [workflows](../../features/workflow/overview). Create and manage AI profiles from [global nav](../../guide/screen-layout) > **Workspace settings** > **AI profiles**. While chatting with the AI agent, you can switch the profile in use from **AI profile** in the input field. ## Types {#types} From **New AI Profile**, choose one of the following. | Type {.nowrap} | Description | | --- | --- | | **Managed** | Uses an AI model managed by Codatum. No API key is required | | **Custom** | Uses an API key for OpenAI / Anthropic / Gemini / Vertex AI / OpenRouter / Fireworks / Amazon Bedrock, and more | **Custom** might not be available, depending on your contract. ## Creating and managing {#create-manage} 1. Open [global nav](../../guide/screen-layout) > **Workspace settings** > **AI profiles**. 2. From **New AI Profile**, choose **Managed** or **Custom**. 3. Enter each item, then select **Create**. You can open an existing profile from the list and change it with **Update**. ## Settings {#settings} ### Name The display name of the profile. ### Model selection / provider / model * **Managed**: choose a model tier (a selection based on intended use) under **Model selection**. You can't specify a provider or an individual model name. * **Custom**: configure the **provider**, **model**, and API key, among other settings. For Amazon Bedrock, configure a Bedrock API key and region. ### Context {#context} Specify content to always reference when the AI agent runs (optional). | Item {.nowrap} | Description | | --- | --- | | **Notebooks and folders** | Loads a linked notebook, or the notebooks within a linked folder. You can also specify folders or notebooks within a teamspace | | **Plain text** | Additional instructions or descriptions passed as text | If you link a folder, the notebooks within it are loaded. If you link a folder within a teamspace, using that AI profile requires view permission on the target folder. ::: warning When a [workflow](../../features/workflow/overview) runs, the AI profile's context isn't loaded. ::: ### Tool permissions {#tool-permissions} Restricts what the AI agent can use, on top of the executing user's permissions. | Item {.nowrap} | Choices / content | | --- | --- | | **Notebook access** | **All accessible notebooks** / **Current notebook only** | | **Connection access** | **All accessible connections** / **Allow only selected** / **Deny selected** | | **Connector access** | **Off** / **Allow only selected connectors** / **All connectors** | | **Web search** | **Off** / **Allow specific domains** / **On** | | **Web fetch** | **Off** / **Allow specific domains** / **On** | For domain specification, you can use formats such as `example.com` or `*.example.com`. ### Sharing {#sharing} Manage which members and groups can use the profile. | Target {.nowrap} | Description | | --- | --- | | **Workspace Owner** | Always included (fixed) | | **Workspace members** | Grants access to all members | | Group / individual members | Add from **Add group or member**. Choose the role: **Owner** or **User** | * **Owner**: can edit the profile, among other things. * **User**: can chat using this AI profile. ### Save conversations to logs When turned on, conversation messages using this AI profile can be reviewed in [Agent usage](./agent-usage#session-details) session details. ### Cost tracking {#cost-tracking} For a **Custom** AI profile, turn on **Cost tracking** to record an estimated cost. The AI profile detail page displays the recorded amount as **This month (estimated)**. For a fixed model, enter the USD price per 1 million tokens for **Input**, **Cached input**, and **Output**. When default pricing is available for the model, the fields are prefilled. Select **Reset to default** to restore the current default pricing. When **Model** is **Auto**, the estimate uses the default pricing for the model selected at runtime. Estimated costs have the following characteristics: * Only usage while cost tracking is on is recorded. * Changing a price doesn't recalculate previously recorded estimates. * Estimates don't include cache-write premiums, provider discounts, batch pricing, or currency conversion. * Some retries and failed requests might not be recorded. * Estimates might differ from the amount billed by the provider. ### Usage limits {#usage-limits} You can set a cost limit per AI profile (optional). There are two kinds of limits, and you can set both. | Item {.nowrap} | Description | | --- | --- | | **Profile limit** | A limit on total usage for this profile. | | **Per-user limit** | A limit on usage started directly by each user. Usage through a [workflow](../../features/workflow/overview) or [API key](../access-and-security/api-key) isn't included. | Specify the amount in USD, and choose a period of **Monthly**, **Weekly**, or **Daily**. Periods must be unique within a scope. You can set up to 3 limits per scope. See [Limits](../../reference/limits#fixed-limits). Periods reset on the UTC calendar, and weeks start on Monday. When any limit is reached, new runs with that profile are rejected. The error includes the reset time in UTC. If you set multiple periods, exceeding any one of them stops new runs. The check runs before a turn starts. An in-progress turn may finish even if it would exceed the limit. * **Custom**: You can configure limits when **Cost tracking** is on. Limits use estimated cost. Turning tracking off means limits are no longer applied, but saved limit settings are kept. * **Managed**: Configure limits under **Usage limits**. Limits use the billed cost of this profile. This is independent of the workspace monthly usage limit; whichever is reached first stops new runs. ### Start screen You can configure the welcome text shown when a chat starts, and suggested prompts (optional). --- --- url: 'https://docs.codatum.com/workspace/codatum-ai/agent-usage.md' description: Check AI agent session and token usage --- # Agent usage (Beta) You can check session and token usage for the [AI agent](../../features/ai-agent/overview). Open it from [global nav](../../guide/screen-layout) > **Workspace settings** > **Agent usage**. Only workspace owners can view it ([Workspace permissions](../../permissions/workspace)). ::: info This feature is in **beta**. The specification might change without notice. ::: Usage data is retained for 30 days ([Limits](../../reference/limits#fixed-limits)). Usage under your contract can be checked from workspace settings > **Usage**. ## Period and filters {#period-filters} You can choose the **period** from the following (default is **Last 30 days**). | Period {.nowrap} | Description | | --- | --- | | **Last 24 hours** | The most recent 24 hours | | **Last 7 days** | The most recent 7 days | | **Last 30 days** | The most recent 30 days | | **Custom range** | Specify a start and end date | From **Add filter**, you can narrow results by the following conditions. | Filter {.nowrap} | Description | | --- | --- | | **Account** | Filter by user or API key | | **User type** | **Member** / **Guest** | | **Report** | Filter sessions that used a report as context | | **AI profile** | Filter by the [AI profile](./ai-profile) used | | **Source** | Filter by where the session was launched from | | **Final status** | **Completed** / **Aborted** / **Error** | The available sources are as follows. | Source {.nowrap} | Description | | --- | --- | | **Full page** | Sessions launched from [global nav](../../guide/screen-layout) > **AI Agent** | | **Side panel** | Sessions launched from **AI Agent** at the bottom right of the screen | | **API** | Sessions launched through the API | | **Slack** | Sessions launched from Slack | ## Overview {#overview} The **Overview** tab shows the following. | Display | Description | | --- | --- | | **Sessions** / **Active users** / **Turns** / **Total tokens** | Totals for the selected period | | **Daily trend** | Usage broken down by AI profile. You can switch between **Sessions** / **Tokens** | | **By AI profile** | Token distribution | | **Account ranking** | Ranked by token usage | ## Sessions {#sessions} The **Sessions** tab lists sessions that match the selected period and filters. Scroll down the list to load more. Select a row to open **Session details**. ### List | Column {.nowrap} | Description | | --- | --- | | **Date** | When the session started | | **Title** | The session title. If unset, **Untitled session** is shown | | **User** | The user, API key, or workflow that started the session | | **AI profile** | The [AI profile](./ai-profile) used | | **Source** | The same categories as in [Source](#period-filters) | | **Turns** | The number of turns in the session | | **Tokens** | The total tokens consumed by the session | | **Final status** | **Completed** / **Aborted** / **Error** | ### Session details {#session-details} **Session details** includes **Session information** and **Turns**. #### Session information | Item {.nowrap} | Description | | --- | --- | | **Date** | When the session started | | **Title** | The session title. If unset, **Untitled session** is shown | | **User** | The user, API key, or workflow that started the session | | **AI profile** | The AI profile used. Existing profiles link to their settings page | | **Source** | Where the session was launched from | | **Page title** | Shown when the source is **Side panel**. The title of the page that was open when the session started | | **Turns** | The number of turns in the session | | **Tokens** | The total tokens consumed by the session | | **Final status** | **Completed** / **Aborted** / **Error** | | **Last updated** | When the session was last updated | | **Session ID** | The session identifier | #### Turns For each turn, you can check the following. | Column {.nowrap} | Description | | --- | --- | | **Turn** | The turn number | | **Started** | When the turn started | | **Ended** | When the turn ended | | **Messages** | The number of messages in the turn | | **Tokens** | The tokens consumed by the turn | Turns with stored message logs can be expanded. Expanding a turn shows **User** / **AI Agent** message text and tool calls (name, duration, and **Succeeded** / **Aborted** / **Failed**). Message logs are stored when **Save conversations to logs** is on for the [AI profile](./ai-profile) used. For sessions where it was off, a notice below the turns list explains that message logs weren't stored. --- --- url: 'https://docs.codatum.com/workspace/codatum-ai/agent-connectors.md' description: Integrations with external tools (MCP / API) used by the AI agent --- # Agent connectors (Beta) An agent connector makes tools and APIs from external services available to the [AI agent](../../features/ai-agent/overview). You can create and manage them from [global nav](../../guide/screen-layout) > **Workspace settings** > **Agent Connectors**. Availability can also be restricted through **Connector access** in [AI profiles](./ai-profile#tool-permissions). ::: info This feature is in **beta**. The specification might change without notice. ::: ## Creating and managing {#create-manage} You need permission to change workspace settings to create, edit, or delete connectors. 1. Open [global nav](../../guide/screen-layout) > **Workspace settings** > **Agent Connectors**. 2. Choose a built-in connector from the **Catalog**, which is shown by default. * Enter a service name in `Search by service name...` to find connectors. * You can filter by the following conditions: * Category (**Collaboration** / **Sales & Marketing** / **Engineering** / **Data & Analytics** / **Operations**) * Market (**Global** / **Japan**) * Authentication scope (**Personal** / **Organization**) * Connector type (**MCP** / **API**) * Status (**Live-tested** / **Not live-tested** / **Upon request**) * Filters start unselected and show every connector. * If you don't select a category, the catalog shows **Popular connectors** and then connectors grouped by category. * Each card shows its type and authentication scope. * Connectors that Codatum has tested show **Live-tested** with a check icon. 3. Review its description, authentication methods, and official website in the catalog detail. * Each available authentication option is grouped in a separate panel. * Its values are paired with explicit labels such as **Authentication method**, **Client registration**, **App setup**, **Credentials**, and **Authentication subject**. * If the provider requires setup in advance, **Required setup before connecting** shows the instructions and any URL you need to register. * If the connector is available for self-service setup, select **Add connector**. * A connector marked **Verification pending** can't be added until live testing is complete. * To request access, select **Contact us** on its detail page. * If it's marked **Upon request**, also select **Contact us** on the detail page. * Confirm the connector and request type, enter optional details, then select **Submit request**. * For a destination not in the catalog, select **Create custom connector** to configure an MCP URL or API manually. 4. If **Required setup before connecting** appears, complete those instructions. Enter the connector settings, then select **Create**. After creation, the **My connectors** tab opens. 5. Use **My connectors** to view, edit, or delete created connectors. ## Types {#types} | Type {.nowrap} | Description | | --- | --- | | **MCP** | Connects to an MCP server and uses its published tools | | **API** | Calls an HTTP API directly | When creating a custom connector, you can choose **MCP** or **API** under **Connector type**. For built-in connectors, the type is already fixed. ## Settings {#settings} Some items aren't shown, depending on the type and authentication method. | Item {.nowrap} | Description | | --- | --- | | **Name** | The connector's display name | | **Built-in connector** | Shown when created from a built-in connector (can't be changed) | | **Overview** | A short description always passed to the agent. For API, you can set this from creation; for MCP, you set it when editing after creation | | **Skill doc** | Detailed instructions loaded only when needed. Shown under the same conditions as **Overview** | | **Server URL** | The MCP connection URL. Can't be changed after creation. Some built-in connectors ask for a data region, tenant, or other destination value to complete the URL | | **Auth scope** | For MCP: **Workspace (API key)** / **Personal (OAuth)** (when the built-in connector offers both). For API: **Workspace** / **Personal** | | **API key header** | The HTTP header name used for MCP API key authentication. It comes from the built-in connector and can't be changed | | **Endpoint prefix** | The API base URL. Can't be changed after creation. Some built-in connectors ask for a store or other destination value to complete it | | **Secret keys** | The key names and values used for API, or for MCP API key authentication. For MCP API key, enter the full header value in the format shown in the form | | **Enabled** | Turning this off disables the connector | For MCP OAuth, you can specify an OAuth client (client ID / client secret) and OAuth scopes under **Advanced settings**. * If the OAuth client is blank and the MCP server supports it, Dynamic Client Registration is used. * If OAuth scopes are blank, the scopes advertised by the server are requested. * If a built-in connector predefines OAuth scopes, the scopes field can't be left empty. For built-in connectors that can't use Dynamic Client Registration, a workspace administrator creates an OAuth app with the provider and enters its client ID when a Codatum shared app isn't available. This applies to the following providers: * Google * Microsoft * GitHub * HubSpot * Salesforce * Box * Asana * Slack * PagerDuty * Gong * Front * Gainsight CS * Dropbox The following providers also require a client secret: * Google * GitHub * HubSpot * Box * Asana * Slack * PagerDuty * Gong * Front * Gainsight CS When a Codatum shared app is available, leave the OAuth client fields blank, or enter your own app credentials to override it. For live-tested connectors that support your own app, the connector catalog details and creation form show the following: * The app creation page * App type * Required values * Official setup guide Set the app's redirect URI (callback URL) to `https://app.codatum.com/oauth/mcp/callback`. How credentials are handled depends on the type and authentication scope. * For MCP (OAuth), each user connects individually using personal authentication from the connector detail screen. * Credentials for MCP (API key) and API (workspace) are shared across the workspace. * Personal-scope API authentication is managed under **Connector authentication** in [global nav](../../guide/screen-layout) > **Workspace settings** > **Personal settings**. ## Built-in connectors {#built-in} The following built-in connectors appear in the catalog. This list may be added to or changed without notice. Connectors marked **Upon request** aren't currently available for self-service setup. The detail page shows the verification status as **Live-tested** or **Not live-tested**. * Codatum has tested connectors marked **Live-tested** with a live service account. * Connectors marked **Not live-tested** are based on official specifications but can't be added until Codatum completes live testing. You can request access from the connector detail page. ### Collaboration {#collaboration} | Name | Type | Connection | Description | | --- | --- | --- | --- | | **Linear** | API | Organization client credentials · Live-tested | Retrieves issues, projects, teams, and more. | | **Airtable** | API | Organization service account · Not live-tested | Retrieves bases, tables, records, fields, and more that the service account can access. | | **Notion** | MCP | Personal OAuth · Live-tested | Connects to workspace search, page operations, and content editing available to the authenticated user. | | **Notion** | API | Organization API key · Live-tested | Retrieves pages, data sources, and users shared with an internal connection. | | **Atlassian** | MCP | Personal OAuth · Live-tested | Connects to Jira issues and the Confluence knowledge base. | | **Gmail** | MCP | Personal OAuth · Own app · Upon request | Connects to Gmail threads, drafts, and mail search. | | **Google Calendar** | MCP | Personal OAuth · Own app · Upon request | Connects to Google Calendar events and availability. | | **Google Chat** | MCP | Personal OAuth · Own app · Upon request | Connects to Google Chat spaces and messages. | | **Google Docs** | MCP | Personal OAuth · Own app · Upon request | Connects to Google Docs. | | **Google Drive** | MCP | Personal OAuth · Own app · Upon request | Connects to Google Drive files and Workspace documents. | | **Google Sheets** | MCP | Personal OAuth · Own app · Upon request | Connects to Google Sheets. | | **Google Slides** | MCP | Personal OAuth · Own app · Upon request | Connects to Google Slides. | | **Google Docs** | API | Organization service account · Live-tested | Retrieves Google Docs shared with the service account. | | **Google Drive** | API | Organization service account · Live-tested | Retrieves files and folders shared with the service account. | | **Google Sheets** | API | Organization service account · Live-tested | Retrieves Google Sheets shared with the service account. | | **Microsoft Outlook Calendar** | MCP | Personal OAuth · Own app · Live-tested | Connects to Outlook calendar. | | **Microsoft Outlook Mail** | MCP | Personal OAuth · Own app · Live-tested | Connects to Outlook mail. | | **Microsoft OneDrive** | MCP | Personal OAuth · Own app · Live-tested | Connects to OneDrive files. | | **Microsoft SharePoint** | MCP | Personal OAuth · Own app · Live-tested | Connects to SharePoint sites, lists, and files. | | **Microsoft Teams** | MCP | Personal OAuth · Own app · Live-tested | Connects to Teams chats and channels. | | **Microsoft User Directory** | MCP | Personal OAuth · Own app · Live-tested | Connects to Microsoft 365 user profiles and org structure. | | **Microsoft Word** | MCP | Personal OAuth · Own app · Live-tested | Connects to Word documents. | | **Slack** | API | Organization API key · Live-tested | Operates on channels, messages, users, and more. | | **Workato** | MCP | Personal OAuth · Live-tested | Connects to recipe-derived tools and business automation context. | | **Composio Connect** | MCP | Organization API key / Personal OAuth · Live-tested | Connects to many apps through Composio Connect. | | **Linear** | MCP | Personal OAuth · Live-tested | Connects to Linear issues and projects. | | **Airtable** | MCP | Personal OAuth · Live-tested | Connects to Airtable bases and records. | | **Asana** | MCP | Personal OAuth · Own app · Live-tested | Connects to Asana tasks and projects. | | **Box** | MCP | Personal OAuth · Own app · Live-tested | Connects to Box files. | | **Canva** | MCP | Personal OAuth · Upon request | Connects to Canva designs. | | **Egnyte** | MCP | Personal OAuth · Live-tested | Connects to Egnyte files. | | **Fireflies** | MCP | Personal OAuth · Live-tested | Connects to Fireflies transcripts. | | **Miro** | MCP | Personal OAuth · Live-tested | Connects to Miro boards. | | **monday.com** | MCP | Personal OAuth · Live-tested | Connects to monday.com boards. | | **Granola** | MCP | Personal OAuth · Live-tested | Connects to Granola meeting notes. | | **Slack** | MCP | Personal OAuth · Own app · Live-tested | Connects to messages, channels, files, users, canvases, and lists. The shared app limits how often history and threads can be read. | | **ClickUp** | MCP | Personal OAuth · Live-tested | Connects to tasks, lists, folders, documents, and chat. | | **Dropbox** | MCP | Personal OAuth · Own app · Live-tested | Connects to files, folders, search, sharing, and file requests. | | **Shortcut** | MCP | Personal OAuth · Live-tested | Connects to stories, epics, and iterations. | | **kintone** | API | Organization API key · Live-tested | Connects to records and operational data in configured apps. | | **Chatwork** | API | Personal API token · Live-tested | Connects to rooms, messages, members, and tasks. | | **Backlog** | API | Personal API token · Upon request | Connects to projects, issues, wikis, and users. | | **ANDPAD** | API | Organization OAuth client · Upon request | Connects to construction and project data. | | **microCMS** | API | Organization API key · Upon request | Connects to content and schemas. | | **TimeRex** | API | Personal OAuth client · Upon request | Connects to scheduling data. | ### Sales & Marketing {#sales-marketing} | Name | Type | Connection | Description | | --- | --- | --- | --- | | **HubSpot** | API | Organization API key · Live-tested | Retrieves CRM contacts, companies, deals, tickets, and more. | | **KARTE** | API | Organization API key · Live-tested | Reviews and edits KARTE campaigns, actions, and segments through KARTE API v2. | | **Shopify** | API | Organization client credentials · Live-tested | Connects to products, orders, customers, inventory, and more through Shopify Admin API. | | **Intercom** | MCP | Personal OAuth · Live-tested | Connects to conversations, contacts, companies, and Help Center content. | | **Salesforce** | MCP | Personal OAuth · Own app · Live-tested | Connects to Salesforce records and queries. | | **Salesforce** | API | Organization client credentials · Live-tested | Connects to Salesforce REST API through an external client app and a dedicated integration user. | | **HubSpot** | MCP | Personal OAuth · Own app · Live-tested | Connects to HubSpot CRM. | | **Attio** | MCP | Personal OAuth · Live-tested | Connects to Attio CRM. | | **Close** | MCP | Personal OAuth · Live-tested | Connects to Close CRM. | | **Semrush** | MCP | Personal API key · Live-tested | Connects to SEO, traffic, backlink, competitor, and project data. | | **Ahrefs** | MCP | Personal OAuth / API key · Live-tested | Connects to SEO, keyword, backlink, and competitor research data. | | **Apollo** | MCP | Personal OAuth · Live-tested | Connects to sales intelligence, prospects, and enrichment. | | **Gong** | MCP | Personal OAuth · Own app · Not live-tested | Connects to account, deal, contact, and revenue intelligence. | | **Klaviyo** | MCP | Personal OAuth · Live-tested | Connects to profiles, campaigns, flows, segments, and delivery metrics. | | **Braze** | MCP | Personal OAuth · Upon request | Connects to campaigns, Canvases, segments, analytics, and catalogs. | | **Customer.io** | MCP | Personal OAuth · Live-tested | Connects to profiles, campaigns, journeys, and delivery metrics. | | **Front** | MCP | Personal OAuth · Own app · Not live-tested | Connects to conversations, inboxes, contacts, messages, and drafts. | | **Gainsight CS** | MCP | Personal OAuth · Own app · Not live-tested | Connects to companies, CTAs, Success Plans, Timeline, and scorecards. | | **Webflow** | MCP | Personal OAuth · Live-tested | Connects to sites, pages, and CMS content. | | **Wix** | MCP | Personal OAuth · Not live-tested | Connects to sites, CRM, stores, and bookings. | | **Sanity** | MCP | Personal OAuth · Live-tested | Connects to content, datasets, and projects. | | **Sansan** | API | Organization API key · Upon request | Connects to people, business card, tag, and organization data after Open API access is coordinated. | | **BASE** | API | Organization OAuth client · Upon request | Connects to shops, products, and orders after Direct API connectors support OAuth. | | **MiiTel** | MCP | Personal provider-managed authentication · Upon request | Connects to call and meeting analytics after provider coordination. | | **スマレジ** | API | Organization OAuth client · Upon request | Connects to sales, product, customer, and inventory data. | | **Re:lation** | API | Organization API key · Upon request | Connects to inquiries, customers, and messages. | | **STORES** | API | Organization OAuth client · Upon request | Connects to commerce data. | | **SalesNow** | API | Organization API key · Upon request | Connects to company data. | | **Mazrica Sales** | API | Organization API key · Upon request | Connects to accounts, deals, and activities. | | **Upflow** | MCP | Personal OAuth · Upon request | Connects to sales conversations and customer insights. | | **amptalk analysis** | API | Organization API key · Upon request | Connects to call transcripts, summaries, and analytics. | ### Engineering {#engineering} | Name | Type | Connection | Description | | --- | --- | --- | --- | | **Datadog** | MCP | Personal OAuth / Organization API key · Live-tested | Connects to Datadog logs, metrics, traces, incidents, and more. | | **GitHub** | API | Organization API key · Live-tested | Retrieves repositories, issues, pull requests, and more. | | **PagerDuty** | API | Organization API key · Live-tested | Retrieves incidents, services, on-call schedules, and more. | | **Sentry** | MCP | Personal OAuth · Live-tested | Connects to issues, projects, events, and more. | | **GitHub** | MCP | Personal OAuth · Own app · Live-tested | Connects to GitHub repositories, issues, and pull requests. | | **Vercel** | MCP | Personal OAuth · Upon request | Connects to Vercel projects and deployments. | | **Buildkite** | MCP | Personal OAuth · Live-tested | Connects to Buildkite pipelines and builds. | | **Netlify** | MCP | Personal OAuth · Live-tested | Connects to Netlify sites and deployments. | | **Pulumi** | MCP | Personal OAuth · Live-tested | Connects to Pulumi stacks. | | **GitLab** | MCP | Personal OAuth · Live-tested | Connects to projects, issues, merge requests, pipelines, and repositories. | | **Cloudflare** | MCP | Personal OAuth / Organization API key · Live-tested | Connects to the Cloudflare API. | | **Grafana Cloud** | MCP | Personal OAuth · Live-tested | Connects to metrics, logs, dashboards, alerts, and incidents. | | **PagerDuty** | MCP | Personal OAuth · Own app · Not live-tested | Connects to incidents, services, schedules, and on-call rotations. | | **HENNGE One** | API | Organization client credentials · Upon request | Connects to identity and access data. | ### Data & Analytics {#data-analytics} | Name | Type | Connection | Description | | --- | --- | --- | --- | | **dbt Cloud** | MCP | Personal OAuth · Live-tested | Connects to dbt Cloud's Semantic Layer, Discovery, and development context. | | **Supabase** | MCP | Personal OAuth · Live-tested | Connects to Supabase projects and schema. | | **Neon** | MCP | Personal OAuth · Live-tested | Connects to Neon projects and branches. | | **ThoughtSpot** | MCP | Personal OAuth · Live-tested | Connects to ThoughtSpot analytics. | | **Morningstar** | MCP | Personal OAuth · Not live-tested | Connects to Morningstar financial data. | | **PostHog** | MCP | Personal OAuth · Live-tested | Connects to product analytics, feature flags, experiments, and session recordings. | | **Amplitude** | MCP | Personal OAuth · Live-tested | Connects to analytics, taxonomy, experiments, cohorts, charts, and dashboards. | | **Mixpanel** | MCP | Personal OAuth · Live-tested | Connects to events, funnels, flows, retention, and product analytics. | | **Hugging Face** | MCP | Personal OAuth · Live-tested | Connects to models, datasets, Spaces, and papers on the Hugging Face Hub. | | **TROCCO** | API | Personal API key · Upon request | Connects to users, transfer jobs, data marts, and workflows. | ### Operations {#operations} | Name | Type | Connection | Description | | --- | --- | --- | --- | | **freee** | MCP | Personal OAuth · Live-tested | Connects to accounting, HR, invoicing, time tracking, and sales operations. | | **マネーフォワード クラウド会計** | MCP | Personal OAuth · Live-tested | Connects to accounting data and operations. | | **Stripe** | MCP | Personal OAuth · Live-tested | Connects to customers, invoices, payments, and document operations. | | **PayPal** | MCP | Personal OAuth · Live-tested | Connects to PayPal payments. | | **Ramp** | MCP | Personal OAuth · Upon request | Connects to Ramp expenses and cards. | | **Paddle** | MCP | Personal OAuth · Live-tested | Connects to billing, subscriptions, and transactions. | | **SmartHR** | API | Organization API key · Live-tested | Connects to employee and HR data. | | **ジョブカン** | API | Organization API key · Upon request | Connects to attendance and back-office data. | | **バクラク** | API | Organization API key · Upon request | Connects to requests, approvals, and expense data after Codatum validates the API integration. | | **カオナビ** | API | Organization client credentials · Upon request | Connects to employee and talent data after client-credentials authentication is supported. | | **LegalOn** | API | Organization API key · Upon request | Connects to contract data. | | **KING OF TIME** | API | Organization API key · Upon request | Connects to attendance, leave, and employee data. | | **Contract One** | MCP | Personal provider-managed authentication · Upon request | Connects to contract data. | --- --- url: 'https://docs.codatum.com/permissions/overview.md' description: 'How permissions work, evaluation rules, and control methods' --- # Permissions overview Codatum has role-based permission management. Every user always has exactly one workspace role. Resources such as connections and teamspaces can also have resource roles, and notebooks and reports can have sharing settings. Whether an operation is allowed is determined by a combination of these. You manage the organization name, country, organization owners, billing address, payment method, and invoices in [Organization settings](../workspace/administration/organization). You change the plan in workspace settings > **Plans**. Whether those operations are allowed is determined by whether you are an organization owner, not by your workspace role. ## Terminology {#terminology} Terms used to describe permissions. For more detailed definitions, such as the relationship between accounts and users, also see [Account](../account/overview#account-and-user) and the [Glossary](../reference/glossary). | Term {.nowrap} | Meaning | | --- | --- | | [User](../account/overview#account-and-user) | An account that belongs to a workspace | | [Group](../workspace/administration/group) | A collection of users that can be granted permissions together. A single group can be assigned multiple resource roles | | Resource | An object such as a notebook, connection, or teamspace | | Operation | An action such as inviting a user or editing a notebook | | [Workspace role](../workspace/administration/user#workspace-roles) | A role assigned to a user within a workspace | | Resource role | A role tied to an individual resource, assigned to a group or an individual user | | Permission | The ability to perform a specific operation, determined by a combination of roles | ## Evaluation rules {#evaluation-rules} ```mermaid flowchart LR Op[Can the operation run?] --> WR{Does the workspace role allow it?} WR -->|No| Deny[Deny] WR -->|Yes| NeedRR{Tied to a resource?} NeedRR -->|No| Allow[Allow] NeedRR -->|Yes| RR{Does the resource role allow it?} RR -->|Yes| Allow RR -->|No| Deny ``` 1. **Roles have a hierarchy**. A lower role's access is also carried by higher roles ([Role hierarchy](#role-hierarchy)). 2. **Operations tied to a resource are evaluated with AND**. They're allowed only when both the workspace role and the resource role allow them. 3. **Multiple roles on the same resource are evaluated with OR**. If any one of them allows the operation, whether granted directly or through a group, it's allowed. 4. **Operations tied only to the workspace are determined by the workspace role alone**. For example, inviting users. For operations determined by the workspace role alone, see [Workspace permissions](./workspace). ## Role hierarchy {#role-hierarchy} "X or higher" in the tables means that role and any higher role can perform the operation. | Type {.nowrap} | From highest to lowest | | --- | --- | | Workspace role | Workspace Owner, Workspace Editor, Workspace Viewer, Workspace Guest | | Connection resource role | Connection Owner, Connection User, Connection Viewer | | Teamspace resource role | Teamspace Owner / Teamspace Editor / Teamspace Viewer (Owner and Editor/Viewer aren't mutually exclusive. For details, see [Teamspace permissions](./resources/teamspace)) | ## Main topics {#topics} * [Workspace permissions](./workspace) * [Group](./resources/group) / [Connection](./resources/connection) / [Teamspace](./resources/teamspace) * [Notebook](./resources/notebook) / [Report](./resources/report) * [Workflow](./resources/workflow) * [Saved query](./resources/query) / [Catalog](./resources/catalog) * [AI agent permissions](../features/ai-agent/overview#permissions) ## Control methods How permissions are determined varies by resource. | Method {.nowrap} | Target | What determines it | | --- | --- | --- | | Resource role | [Group](./resources/group) | Group Owner (resource role) | | Resource role | [Connection](./resources/connection) | Access level and the granted resource role | | Resource role | [Teamspace](./resources/teamspace) | The granted resource role | | Resource sharing settings | [Notebook](./resources/notebook) / [Report](./resources/report) | The access scope of the root folder, and [additional notebook permissions](../features/notebook/sharing/additional-permissions/overview) or report sharing settings | | Owner assignment | [Workflow](./resources/workflow) | The owners (users or groups) assigned to each workflow. Creation and managing all workflows are governed by the workspace role | | Derived | [Saved query](./resources/query) / [Catalog](./resources/catalog) | The permissions of the linked connection. There's no dedicated resource role | | Follows the executing user's permissions | [AI agent](../features/ai-agent/overview#permissions) | No dedicated resource role. Additional restrictions come from the AI profile's tool permissions | ## Access scope {#access-scope} For some resources, such as notebooks, the **type of root folder** they belong to becomes the access scope, which determines how permissions are evaluated. For the conditions for each operation, see [Notebook access scope](./resources/notebook#access-scope). | Scope {.nowrap} | Key points | | --- | --- | | Workspace | Workspace members can access it according to their workspace role | | Teamspace | Access is determined by the teamspace resource role | | Private | Under the "Private" root folder. Only the owner, if they're a Workspace Editor or higher, can operate on it | | Shared | Users and groups granted permissions through [additional notebook permissions](../features/notebook/sharing/additional-permissions/overview) can access it. It appears in the **Shared folder** on the recipient's side | ## Relationship with credentials {#credentials} | Credential {.nowrap} | How permissions apply | | --- | --- | | Browser login (account) | Evaluated by the workspace role / resource role of the user in their workspace | | PAT | Capped by the issuing account's user permissions, and further narrowed by the permission boundary (connections / notebooks / tags) specified at issuance. See [Personal Access Tokens](../account/settings/pat#issue-token) for issuance, and [Personal Access Tokens](../workspace/access-and-security/pat#operations) for managing them within a workspace | | API key | Tied to the workspace. Only usable for granted [signed embeds](../features/notebook/sharing/signed-embed/overview). See [API keys](../workspace/access-and-security/api-key) for details | --- --- url: 'https://docs.codatum.com/permissions/workspace.md' description: Permissions for operations determined by the workspace role alone --- # Workspace permissions For operations tied only to the workspace, whether they're allowed is determined by the user's [workspace role](../workspace/administration/user#workspace-roles). ## Operations "X or higher" in the table means that role and any higher role can perform the operation. For the definition of the hierarchy, see [Role hierarchy](./overview#role-hierarchy). | Operation | Category {.nowrap} | Required workspace role {.nowrap} | | --- | --- | --- | | Inviting and removing users / changing a user's role | Users | Workspace Owner | | Viewing the audit log and user activity history | Audit logs | Workspace Owner | | Viewing [Agent usage](../workspace/codatum-ai/agent-usage) | Codatum AI | Workspace Owner | | Viewing information about the workspace | Workspace | Workspace Viewer or higher | | Changing workspace settings (including policy, security, API key, and PAT management; excluding plan changes) | Workspace | Workspace Owner | | Viewing information for all groups | Group | Workspace Viewer or higher | | Creating a group | Group | Workspace Owner | | Creating a connection | Connection | Workspace Editor or higher | | Creating a teamspace | Teamspace | Workspace Editor or higher | | Creating and editing [tag definitions](../workspace/data-management/tag#tag-definition) | Tag | Workspace Editor or higher | | Creating a workflow | Workflow | Workspace Editor or higher | | Managing workflows | Workflow | Workspace Owner | Inviting guests from the report screen isn't determined by the workspace role alone. For details, see [Report permissions](./resources/report#guest-sharing) and [Invitations and joining](../workspace/administration/invite#guest-invite-from-report). Whether you can manage billing or change the plan isn't determined by the workspace role. It's determined by whether you are an organization owner. For details, see [Organization settings](../workspace/administration/organization#owners) and [Workspace subscriptions](../workspace/overview#subscriptions). Editing or deleting a group, and changing its members, can be done by the Workspace Owner as well as the Group Owner. For details, see [Group](./resources/group). For operations tied to resources such as connections, notebooks, and reports, see [Permissions overview](./overview) and the page for each resource. --- --- url: 'https://docs.codatum.com/permissions/resources/group.md' description: Group resource roles and operations --- # Group permissions Whether an operation on a group is allowed is determined by the [workspace role](../../workspace/administration/user#workspace-roles), plus the resource role granted on the group. For how groups are used, see [Group](../../workspace/administration/group). ## Resource role | Role {.nowrap} | Summary | | --- | --- | | Group Owner | Can manage the target group even without being a Workspace Owner | Up to 3 Group Owners can be added ([Fixed limits and constraints](../../reference/limits#fixed-limits)). ## Operations and required roles | Operation | Required role | | --- | --- | | Viewing the list of groups within the workspace | Workspace Viewer or higher | | Creating a group | Workspace Owner | | Deleting a group / editing its settings / adding and removing members / adding and removing owners | Workspace Owner, or Group Owner | --- --- url: 'https://docs.codatum.com/permissions/resources/connection.md' description: Connection permissions based on access level and resource role --- # Connection permissions Whether an operation on a connection is allowed is determined by the [workspace role](../../workspace/administration/user#workspace-roles), plus the access level and resource role. * **[Access level](#access-level)** determines who can use the connection. * **Resource role** determines which operations are allowed within that scope. For example, for a connection with an **access level of Protected**, only users and groups granted a permission can use the connection. Within that group, a **Connection User** is allowed to run SQL and view the results, while a **Connection Viewer** is only allowed to view the results. For a feature overview, see [Connection](../../features/connection/overview). ## Access level {#access-level} | Access level {.nowrap} | Description | | --- | --- | | Workspace | Members in the workspace can access it according to their workspace role | | Protected | Only users and groups granted a resource role can access it. The Workspace Owner can edit the connection's permissions | | Private | Only users and groups granted a resource role can access it. Even the Workspace Owner can't edit the connection's permissions | ::: tip The Protected and Private access levels are an **optional feature**. Depending on your contract, they might not be available. ::: ## Resource role | Role {.nowrap} | Summary | | --- | --- | | Connection Owner | Can edit and delete the connection, and change its permission settings | | Connection User | Can run SQL, view the results and tables, and publish related reports | | Connection Viewer | Can view the results and tables | Up to 3 Connection Owners can be added ([Fixed limits and constraints](../../reference/limits#fixed-limits)). **Codatum Data Connection** is an exception: Workspace Owners manage it, and you can't add or remove individual Connection Owners. ## Operations and required roles "X or higher" in the tables means that role and any higher role can perform the operation. Changing a connection's permission settings includes changing the access level and granting or changing resource roles. ### Access level: Workspace No individual permission grant is needed for members. Whether an operation is allowed is mainly determined by the workspace role. | Operation | Required role | | --- | --- | | Creating a connection | Workspace Editor or higher | | Listing connection names | Workspace Viewer or higher | | Editing and deleting a connection | Workspace Owner, or Connection Owner | | Changing a connection's permission settings | Workspace Owner, or Connection Owner | | Running SQL on a connection / downloading execution results | Workspace Editor or higher | | Getting a connection's SQL execution results and table information | Workspace Viewer or higher | ### Access level: Protected Only users and groups granted a resource role can use this connection. The Workspace Owner can change the connection's permission settings. **Codatum Data Connection** has the Protected access level when it's created. Workspace Owners manage it. You can't add or remove individual Connection Owners. | Operation | Required role | | --- | --- | | Creating a connection | Workspace Editor or higher | | Listing connection names | Workspace Viewer or higher | | Editing and deleting a connection | Workspace Owner, or (Workspace Viewer or higher and Connection Owner) | | Changing a connection's permission settings | Workspace Owner, or (Workspace Viewer or higher and Connection Owner) | | Running SQL on a connection / downloading execution results | Workspace Editor or higher, and Connection User or higher | | Getting a connection's SQL execution results and table information | Workspace Viewer or higher, and Connection Viewer or higher | ### Access level: Private Only users and groups granted a resource role can use this connection. Even the Workspace Owner can't change the connection's permission settings. | Operation | Required role | | --- | --- | | Creating a connection | Workspace Editor or higher | | Listing connection names | Workspace Viewer or higher, and Connection Viewer or higher | | Editing and deleting a connection | Workspace Viewer or higher, and Connection Owner | | Changing a connection's permission settings | Workspace Viewer or higher, and Connection Owner | | Running SQL on a connection / downloading execution results | Workspace Editor or higher, and Connection User or higher | | Getting a connection's SQL execution results and table information | Workspace Viewer or higher, and Connection Viewer or higher | Operations on saved queries and the catalog also follow the permissions of the connection they're linked to. For details, see [Query](./query) and [Catalog](./catalog). --- --- url: 'https://docs.codatum.com/permissions/resources/teamspace.md' description: Teamspace resource roles and operations --- # Teamspace permissions Whether an operation on a teamspace is allowed is determined by the [workspace role](../../workspace/administration/user#workspace-roles), plus the teamspace's resource role. Operations on notebooks within a teamspace are also determined through this resource role (for details, see [Notebook](./notebook)). For a feature overview, see [Teamspace](../../workspace/administration/teamspace). ## Resource role Teamspace Owner and Teamspace Editor / Viewer aren't mutually exclusive. If a user has more than one, the broader permission applies. | Role {.nowrap} | Summary | | --- | --- | | Teamspace Owner | Can manage the target teamspace even without being a Workspace Owner | | Teamspace Editor | Can edit notebooks and folders within the teamspace | | Teamspace Viewer | Can view notebooks and folders within the teamspace | Up to 3 Teamspace Owners can be added ([Fixed limits and constraints](../../reference/limits#fixed-limits)). ## Operations and required roles | Operation | Required role | | --- | --- | | Getting the names of all teamspaces | Workspace Viewer or higher | | Creating a teamspace | Workspace Editor or higher | | Renaming a teamspace / adding or removing owners / deleting / changing permissions | Workspace Owner, or (Workspace Viewer or higher and Teamspace Owner) | For the roles required to view, edit, share, and publish notebooks within a teamspace, see the operations table (scope: Teamspace) in [Notebook](./notebook#scope-teamspace). --- --- url: 'https://docs.codatum.com/permissions/resources/notebook.md' description: Notebook permissions based on access scope and sharing settings --- # Notebook permissions Whether an operation on a notebook is allowed is determined by the [workspace role](../../workspace/administration/user#workspace-roles), plus the **root folder** the notebook belongs to (its access scope). For a feature overview, see [Notebook](../../features/notebook/overview). ## Access scope {#access-scope} The access scope is determined by the **root folder** the notebook is placed in. For how root folder names map to this, also see [Folder](../../features/notebook/folder). | Scope {.nowrap} | Description | | --- | --- | | [Workspace](#scope-workspace) | A notebook placed under the "Workspace" root folder. Members can access it according to their workspace role | | [Teamspace](#scope-teamspace) | A notebook placed under the "(teamspace name)" root folder. Access is determined by the teamspace's resource role | | [Private](#scope-private) | A notebook placed under the "Private" root folder. Only the owner, if they're a Workspace Editor or higher, can operate on it | | [Shared](#scope-shared) | A notebook placed under a "Shared folder". Who can access it is determined by [additional notebook permissions](../../features/notebook/sharing/additional-permissions/overview) | ::: tip The Private, Teamspace, and Shared access scopes are an **optional feature**. Depending on your contract, they might not be available. ::: ## Resource role (when shared) Roles used for notebooks in the shared scope. Who they're granted to is decided through [additional notebook permissions](../../features/notebook/sharing/additional-permissions/overview). | Role {.nowrap} | Summary | | --- | --- | | Notebook Editor | Can edit the notebook | | Notebook Viewer | Can view the notebook | For notebooks within a teamspace, the teamspace's resource role (Editor / Viewer / Owner) is used for notebook operations. ## Operations and required roles Running SQL and getting execution results on a notebook aren't determined by notebook permissions — they're **determined by the permissions of the target [connection](./connection)**. ### Access scope: Workspace {#scope-workspace} Notebooks under the "Workspace" root folder. Whether an operation is allowed is determined by the workspace role. | Operation | Required role | | --- | --- | | Viewing content / commenting | Workspace Viewer or higher | | Editing a notebook | Workspace Editor or higher | | Moving or deleting a notebook / editing or deleting a folder | Workspace Editor or higher | ### Access scope: Teamspace {#scope-teamspace} Notebooks under the "(teamspace name)" root folder. Determined by the permissions granted in [Teamspace](./teamspace). | Operation | Required role | | --- | --- | | Viewing content / commenting | Workspace Viewer or higher, and Teamspace Viewer or higher | | Editing a notebook | Workspace Editor or higher, and Teamspace Editor or higher | | Moving or deleting a notebook / editing or deleting a folder | Workspace Editor or higher, and Teamspace Editor or higher | | Sharing with users or groups | Workspace Viewer or higher, and Teamspace Editor or higher | ### Access scope: Private {#scope-private} Notebooks under the "Private" root folder. Only the owner, if they're a Workspace Editor or higher, can operate on them. | Operation | Required role | | --- | --- | | Viewing content / commenting | Workspace Editor or higher | | Editing a notebook | Workspace Editor or higher | | Moving or deleting a notebook / editing or deleting a folder | Workspace Editor or higher | | Sharing with users or groups | Workspace Editor or higher | ### Access scope: Shared {#scope-shared} Notebooks under a "Shared folder". Users and groups granted permissions through [additional notebook permissions](../../features/notebook/sharing/additional-permissions/overview) can access them. Notebooks accessed only through sharing can't be deleted or moved, even with edit permission. | Operation {.nowrap} | Required role | | --- | --- | | Viewing content / commenting | Workspace Viewer or higher, and Notebook Viewer or higher | | Editing a notebook | Workspace Editor or higher, and Notebook Editor | For the conditions required to publish a report, see [Report](./report). --- --- url: 'https://docs.codatum.com/permissions/resources/report.md' description: 'Report viewing permission, guest sharing, and conditions for publishing' --- # Report permissions Whether an operation on a report is allowed is determined by the [workspace role](../../workspace/administration/user#workspace-roles), plus the report's sharing settings. Because reports are read-only, the only resource role is Viewer. For a feature overview, see [Report](../../features/notebook/sharing/report/overview). ## Resource role | Role {.nowrap} | Summary | | --- | --- | | Report Viewer | Can view the report | ## Operations and required roles A Report Viewer can view the report. [Comments](../../features/notebook/comment#report-comments) can be used unless comments are disabled. Whether SQL can be re-run, parameters edited, downloads made, and the Explorer used is determined by the **publish settings** (report type and options) chosen when the report was published. For the content of publish settings, see [Report publish settings](../../features/notebook/sharing/report/overview#publish-settings). Changing publish settings requires republishing. | Operation | Condition in publish settings | | --- | --- | | Re-running SQL / refreshing execution results | Refreshable report or interactive report | | Editing parameters | Interactive report | | Downloading source data | Downloads enabled | | Using the Explorer | Explorer enabled | ::: tip Unlike running SQL on a notebook, re-running SQL and getting or downloading execution results within a report don't require [connection](./connection) permissions. If allowed by the [publish settings](../../features/notebook/sharing/report/overview#publish-settings), a Report Viewer can run them. ::: ## Sharing targets A report can be shared with a user or a group. Sharing grants Report Viewer. ### Guest {#guest-sharing} A report can be shared with a workspace [guest](../../workspace/administration/user#member-and-guest). * A guest who has already joined the workspace can be shared with directly. * If they haven't joined yet, you can invite them as a guest by specifying an email address. Once they accept the invitation, they're added to the workspace as a guest and can view the target report. For the steps, see [Invitations and joining](../../workspace/administration/invite#guest-invite-from-report). A guest can perform the same operations as a Report Viewer (within the scope of the publish settings). They can't access notebooks or connections. If the [workspace policy](../../workspace/access-and-security/policy#policy-settings) disables guest invitations to reports by Workspace Editors, only the Workspace Owner can invite guests. ### Members and groups {#member-group-sharing} Besides guests, a report can also be shared with [members](../../workspace/administration/user#member-and-guest) or groups. Because guests can't belong to a group, sharing with a group only reaches members. ## Publishing and management operations The permissions required to publish and manage a report are based on the edit permission of the source notebook it was published from. For the roles required to edit a notebook, see [Notebook](./notebook). However, notebooks in the shared scope can't be published as a report even with edit permission. | Operation | Required condition | | --- | --- | | Publishing a report / changing report permissions | Edit permission on the source notebook, and Connection User or higher for every connection used by the published pages | | Deleting a report / editing report settings | Edit permission on the source notebook | --- --- url: 'https://docs.codatum.com/permissions/resources/query.md' description: 'Saved query permissions, derived from connection permissions' --- # Query permissions Saved queries don't have a dedicated resource role. Whether an operation is allowed follows the permissions of the linked [connection](./connection). | Operation | Required permission | | --- | --- | | Viewing a query (list, details, SQL text, execution results) | Being able to get the connection's SQL execution results and table information, for the linked connection | | Running a query's SQL / creating, updating, deleting, or moving it | Being able to run SQL on the linked connection | | Creating, moving, or deleting a query folder | Being able to run SQL on the linked connection | For a feature overview, see [Query](../../features/saved-query/overview). --- --- url: 'https://docs.codatum.com/permissions/resources/catalog.md' description: 'Catalog permissions, derived from connection permissions' --- # Catalog permissions The catalog doesn't have a dedicated resource role. Whether you can view a table or edit its annotations (description and tags) follows the permissions of the [connection](./connection) that table is synced from. When the same table is synced from multiple connections (see [Table identity](../../features/catalog/metadata-sync#table-identity)), you can operate on it if you have the required permission on **at least one** of its source connections. | Operation {.nowrap} | Required permission | | --- | --- | | Viewing table information | Being able to get the connection's SQL execution results and table information, for at least one source connection | | Editing descriptions and tags | Being able to run SQL on at least one source connection | | Creating and editing tag definitions | [Workspace permissions](../workspace) (Workspace Editor or higher). For operations on definitions, see [Tag](../../workspace/data-management/tag#tag-definition) | Metadata for saved queries in the catalog follows the permissions in [Query](./query). For a feature overview, see [Catalog](../../features/catalog/overview). --- --- url: 'https://docs.codatum.com/permissions/resources/workflow.md' description: Workflow permissions based on owner assignment and workspace role --- # Workflow permissions Whether an operation on a workflow is allowed is determined by the [workspace role](../../workspace/administration/user#workspace-roles) and the workflow's **owner** assignment. * **Creating** a workflow, and **managing** a workflow you don't own, are determined by the workspace role, as described in [Workspace permissions](../workspace). * Viewing, editing, running, and deleting an individual workflow is determined by that workflow's owner (or the Workspace Owner). For a feature overview, see [Workflow](../../features/workflow/overview). ## Owners {#owners} An owner is a user or a group. Immediately after creation, only the creator is an owner. You can change this from **Owners** > **Edit** > **Add owner** on the detail screen. A workflow can have 1 to 30 owners ([Fixed limits and constraints](../../reference/limits#fixed-limits)). Users and groups assigned as owners can view, edit, run, and delete that workflow. ## Operations and required permissions | Operation | Required permission | | --- | --- | | Viewing the list and details | Owner of the workflow, or Workspace Owner | | Creating and duplicating | Workspace Editor or higher | | Editing, enabling, disabling, deleting, running manually, and changing owners | Owner of the workflow, or Workspace Owner | Whether SQL run via Run Query is allowed is also determined by the permissions of the target [connection](./connection). --- --- url: 'https://docs.codatum.com/account/overview.md' description: 'What an account is, its relationship to users, and account settings' --- # Account An account is the unit you use to log in to Codatum. It's created through [sign-up](./signup), and a single account can belong to multiple workspaces. ## Accounts and users {#account-and-user} A single account can belong to multiple workspaces. In each workspace it belongs to, it's treated as a user of that workspace and is always assigned exactly one [workspace role](../workspace/administration/user#workspace-roles). ```mermaid flowchart TB A[Account Login unit, shared across workspaces] A --> U1[User A Member of Workspace X] A --> U2[User B Guest of Workspace Y] ``` | Term {.nowrap} | Meaning | | --- | --- | | Account | The unit you use to log in to Codatum. A single account is shared across workspaces | | User | An account that belongs to a given workspace. Includes members and guests | For details on members, guests, and workspace roles, see [User](../workspace/administration/user). For joining a workspace, see [Invitations and joining](../workspace/administration/invite). ## Account settings {#account-settings} You can open account settings from the avatar icon at the bottom of the [global nav](../guide/screen-layout) > **Account settings**. | Menu {.nowrap} | Content | | --- | --- | | [General](./settings/basic) | Profile, theme, language, and more | | [Sign-in & security](./settings/login) | Email address, sign-in methods, multi-factor authentication | | [SQL editor preferences](./settings/editor) | Indentation, autocomplete, tooltips, and more | | [Keyboard shortcuts](./settings/keyboard-shortcut) | View and change shortcuts | | [Notification preferences](./settings/notification) | In-app and email notifications | | [Personal Access Tokens](./settings/pat) | Create, update, suspend, and revoke the tokens you issue | --- --- url: 'https://docs.codatum.com/account/signup.md' description: Creating a new account and what happens after you sign up --- # Sign-up You create your Codatum account through sign-up. There are two ways to register. | Method {.nowrap} | Overview | | --- | --- | | Register with Google | Authenticate with a Google account, then register your profile | | Register with email | Enter an email confirmation code, set a password, then register your profile | Profile registration requires your full name and similar information. To add or change sign-in methods after your account is created, see [Sign-in & security](./settings/login). ## After signing up {#after-signup} After your account is created, you're taken to the [workspace selection screen](../guide/navigation#workspace-icon). From there, you do one of the following. * **Join** or **Decline** an [invitation](../workspace/administration/invite#email-invite) you've received * **Join** or **Decline** an [organization owner invitation](../workspace/administration/organization#invitee-flow) you've received * **Join** a workspace you can join through an [allowed domain](../workspace/administration/invite#allowed-domains) * Create a new organization If you opened an [invite link](../workspace/administration/invite#invite-link), you're taken back to that link after signing up and can join the workspace directly, without going through the selection screen. For details on invitations and joining a workspace, see [Invitations and joining](../workspace/administration/invite). For how to open the selection screen later, see [Workspace icon](../guide/navigation#workspace-icon). --- --- url: 'https://docs.codatum.com/account/settings/basic.md' description: 'Account profile, theme, and language settings' --- # General In **General** under [account settings](../overview#account-settings), you can manage your profile and [theme and language](#interface) settings. These settings are scoped to your account and shared across every workspace you belong to. ## Profile | Item {.nowrap} | Description | | --- | --- | | Account ID | The ID that uniquely identifies your account | | Full name | Your full display name | | Nickname | A short display name | | Profile image | The image used as your avatar | ## Interface {#interface} | Item {.nowrap} | Description | | --- | --- | | Theme | **Light theme** / **Dark theme** / **Sync with system** | | Language | **Japanese** / **English**, and other options depending on your browser's language settings, plus **Sync with browser** | ### Language * If you select a locale other than Japanese, **the UI is displayed in English** * The selected locale also affects the display of things like number and date formats in charts ### Common notes * You can also change these from the avatar menu in the [global nav](../../guide/screen-layout) (see [Navigation](../../guide/navigation#nav-bottom)) * These settings are stored in your browser, so they might persist even if you switch accounts ## Danger zone You can **delete your account**. Deleting it removes your account information from Codatum and you'll no longer be able to log in to the service. To delete your account, you must first leave **every workspace** you belong to. You must also leave every [organization](../../workspace/administration/organization#owners) you belong to. The last organization owner can't leave. Invite another owner first. --- --- url: 'https://docs.codatum.com/account/settings/login.md' description: Account authentication methods and multi-factor authentication --- # Sign-in & security In **Sign-in & security** under [account settings](../overview#account-settings), you can manage your email address, sign-in methods, and multi-factor authentication. These settings are scoped to your account and shared across every workspace you belong to. ## Email You can check your current email address and **change email**. ## Sign-in methods You can use multiple sign-in methods together. You can't remove the last one. | Method {.nowrap} | Description | | --- | --- | | Password | Authentication with an email address and password. You can **change password** or **remove password** (if you have another sign-in method). If it isn't set up yet, you can add it | | Sign in with Google | Single sign-on with a Google account. You can connect or disconnect it | ## Multi-factor authentication {#account-mfa} | Method {.nowrap} | Description | | --- | --- | | Phone number (SMS) | Authenticates with an SMS sent to a registered phone number. You can **add phone number** / **remove** | | Authenticator app | Authenticates with an authenticator app such as Google Authenticator or Microsoft Authenticator. You can **add authenticator app** / **remove** | If the workspace enforces MFA for Password sign-in, or applies IP access control, see [MFA control](../../workspace/access-and-security/security#mfa-control) and [IP access control](../../workspace/access-and-security/security#ip-access-control). --- --- url: 'https://docs.codatum.com/account/settings/editor.md' description: 'Display, autocomplete, and tooltip settings for the SQL editor' --- # SQL editor preferences In **SQL editor preferences** under [account settings](../overview#account-settings), you can customize how the SQL code editor behaves. For customizing keyboard shortcuts, see [Keyboard shortcuts](./keyboard-shortcut). These settings are scoped to your account and shared across every workspace you belong to. Changes are saved immediately, and you can restore the defaults with **Reset all**. ## Basic | Item | Description | | --- | --- | | Convert Tab to half-width space | When on, converts tab input into half-width spaces. The number of characters is **2 characters** or **4 characters** | | Tab display size | The tab display width when **Convert Tab to half-width space** is off (**2 characters** or **4 characters**) | | Prefer lowercase for reserved words and functions | Uses lowercase as much as possible when applying formatters and autocomplete | | Add alias to Table / SQL Block reference by default | Automatically adds an alias when you insert a reference | | Disable AI code suggestion | Lets you disable AI code suggestions for yourself, even if AI Suggestion is enabled for the workspace | | Disable Enter key for applying autocomplete | The Enter key inserts a line break instead of applying autocomplete | ## Input completion | Item {.nowrap} | Description | | --- | --- | | Enable input completion | The overall on/off switch for autocomplete while writing SQL | | Enable function completion | Autocomplete for functions like `COUNT`, `SUM`, and `MAX` | | Enable reserved words and data types completion | Autocomplete for things like `SELECT` and `LEFT JOIN` | | Enable code snippets completion | Autocomplete for code snippets. On by default | | Enable columns completion | Suggests columns from tables referenced in the SQL block, and from other SQL blocks | Disabling input completion also disables the completion items under it. ## Tooltip | Item | Description | | --- | --- | | Enable tooltip for function reference | Shows the function reference when the cursor is right after a function's `(` or `)` | --- --- url: 'https://docs.codatum.com/account/settings/keyboard-shortcut.md' description: Viewing and changing keyboard shortcuts --- # Keyboard shortcuts In **Keyboard shortcuts** under [account settings](../overview#account-settings), you can customize shortcut keybinds. These settings are scoped to your account and shared across every workspace you belong to. ## Overview * You can search by shortcut name, label, or keybind * You can change the keybind for each shortcut * **Reset to defaults** restores every shortcut to its default value The key notation shown depends on your OS and keyboard layout. Check the on-screen list for the actual assignment. The **Mod** modifier key is ⌘ on macOS and Ctrl on Windows / Linux. ## Common defaults Here are some representative defaults. You can change any item in this list from this screen. | Shortcut {.nowrap} | Default (macOS) | Default (Windows / Linux) | | --- | --- | --- | | **Search** | ⌘+K | Ctrl+K | | **AI Assistant** | ⌘+L | Ctrl+L (opens or closes the [AI Assistant](../../features/ai-assistant/overview#open) or [AI agent](../../features/ai-agent/overview#open) panel) | | **Toggle left sidebar** | ⌘+M | Ctrl+M | | **Execute SQL** | ⌘+Enter | Ctrl+Enter | | **Apply formatter to SQL** | ⌘+Shift+F | Ctrl+Shift+F | | **Comment-out** | ⌘+/ | Ctrl+/ | **Run all** for a notebook is ⌘+Shift+Enter (Ctrl+Shift+Enter on Windows / Linux). This shortcut isn't included in the customization list. --- --- url: 'https://docs.codatum.com/account/settings/notification.md' description: In-app and email notification settings --- # Notification preferences In **Notification preferences** under [account settings](../overview#account-settings), you can manage [notification channels](#notification-channels) and settings for each event. **Notification preferences can be set per workspace.** Use **Workspace to set notification settings** at the top of the screen to switch the target workspace. ## Notification channels {#notification-channels} For each event, you can turn the following channels on or off independently. | Channel {.nowrap} | Description | | --- | --- | | On Codatum | In-app notifications | | Email | Email notifications | * When in-app notifications are enabled, they appear in the **Notifications** menu at the top of the [global nav](../../guide/screen-layout) * Email notifications can only be enabled when the corresponding in-app notification is on ## Notification events you can configure ### Notebooks | Event {.nowrap} | Description | | --- | --- | | Mention in notebook | A mention in the body of a notebook (see [Comment](../../features/notebook/comment#mention)) | | Mention in comment | A mention in a notebook comment (see [Comment](../../features/notebook/comment#mention)) | | Reply in comment | A reply to a notebook comment (see [Comment](../../features/notebook/comment)) | ### Reports | Event {.nowrap} | Description | | --- | --- | | Mention in comment | A mention in a report comment (see [Comment](../../features/notebook/comment#report-comments)) | | Reply in comment | A reply to a report comment (see [Comment](../../features/notebook/comment#report-comments)) | | Published | When a report containing a connection you own is published | If the report feature isn't enabled for the workspace, this section isn't shown. ### Public links | Event {.nowrap} | Description | | --- | --- | | Published | When a public link containing a connection you own is published | ### Signed embeds | Event {.nowrap} | Description | | --- | --- | | Published | When a signed embed containing a connection you own is published | If the signed embed feature isn't enabled for the workspace, this section isn't shown. ### Connections | Event {.nowrap} | Description | | --- | --- | | Connection sync job failed | When the sync job for a connection you own fails | | Connection sync job warning | When a warning occurs in the sync job for a connection you own | --- --- url: 'https://docs.codatum.com/account/settings/pat.md' description: Creating and managing the personal access tokens you issue --- # Personal Access Tokens (Beta) In **Personal Access Tokens** under [account settings](../overview#account-settings), you can [issue](#issue-token) and [manage](#manage-tokens) PATs (personal access tokens) for operating Codatum from the [Codatum CLI](../../features/cli/overview). PATs are issued per workspace. A [Workspace Owner](../../workspace/administration/user#workspace-roles) can view and revoke PATs issued within the workspace from workspace settings. For details, see the workspace [Personal Access Tokens](../../workspace/access-and-security/pat#operations) page. ::: info This feature is in **beta**. The specification might change without notice. ::: ## Prerequisites * If the [workspace policy](../../workspace/access-and-security/policy#policy-settings) prohibits using the Codatum CLI, this menu isn't shown * [Workspace guests](../../workspace/administration/user#member-and-guest) can't use PATs ## Issuing a token {#issue-token} 1. Select **Issue new token** 2. Enter the following, then select **Issue** | Item {.nowrap} | Description | | --- | --- | | Name | An identifying name for the token | | Expiration | You can set this in 1-day increments, up to 365 days (see [Limits](../../reference/limits#fixed-limits)) (you can't issue a token with no expiration) | | Restrict token permissions | By default, a token inherits all of the issuer's permissions. To grant only a subset of those permissions, turn this on and narrow the scope to specific connections, notebooks, or tags. For an overview, see [Permissions overview](../../permissions/overview#credentials) | The plaintext token **is shown only once, right after you issue it, and can't be retrieved again**. Copy it and store it somewhere safe, and don't share it with anyone else. For CLI usage instructions, see the [Codatum CLI documentation](https://cli-docs.codatum.com). ## Managing tokens {#manage-tokens} * You can change the name or permission restrictions of a token that hasn't expired * You can **suspend** a token that hasn't expired * You can **resume** a suspended token to make it usable again * You can immediately disable a token that hasn't expired by **revoking** it * Once revoked, a token can't be reactivated * A token whose expiration has passed becomes **expired** and is automatically revoked * An expired token can't be reactivated * A Workspace Owner can **suspend** or **revoke** any token in the workspace * For details, see [Personal Access Tokens](../../workspace/access-and-security/pat#operations) --- --- url: 'https://docs.codatum.com/reference/limits.md' description: A list of the numeric limits documented here --- # Limits ::: info The values on this page reflect the current specification and might change without notice. Some limits aren't listed here. To check the limits that actually apply, see the screen for each feature, or **Usage** in workspace settings. ::: ## Fixed limits {#fixed-limits} The following items have a fixed limit regardless of your contract. | Item | Limit | | --- | --- | | Connection owners | Up to 3 | | Teamspace owners | Up to 3 | | Group owners | Up to 3 | | Notebook size | A warning is shown when it exceeds 1MB Can't be edited once it exceeds 10MB | | Grid page columns | 1-60 (default 12) | | Grid page row height | 10-120px (default 60px) | | Metadata sync: number of synced schemas (datasets) | Up to 200 | | Metadata sync: number of tables per schema | Up to 1,000 | | Catalog table preview | Up to 100 rows | | Query folder depth | Up to 5 | | Audit log retention | 1 year | | Agent usage retention | 30 days | | Public link expiration | 1-90 days (when enabled; default is 30 days) | | Report cache duration | Up to 24 hours (default 24 hours; 0 disables caching; in 10-minute increments) | | Signed embed token expiration (`expires_in`) | Default 3600 seconds, up to 86400 seconds | | Signed embed cache max age (`cache_max_age`) | Default 86400 seconds, up to 86400 seconds (0 disables caching) | | Workflow steps | Up to 20 | | Workflow owners | Up to 30 | | Workflow email recipients | Up to 20 | | Workflow Run Query results (used by later steps) | Up to 20 rows | | Text multi select parameter choices | Up to 1,000 | | PAT expiration | 1-365 days | | Email invitation expiration (workspace / organization owner) | 7 days from creation (7 days from resend if resent) | | Chart rendering data points | Up to 1,000 rows | | Chart frames (grid layout) | Up to 16 | | Pivot table rows/columns (when processed by SQL) | Up to 30 each (excess is aggregated into `(Others)`) | | Explorer Limit (rows fetched) | Up to 1,000 rows | | Explorer distribution tab target columns | Up to 5 | | AI profile usage limits | Up to one Monthly, Weekly, and Daily limit each for profile limit and per-user limit | ## Limits that vary by contract {#plan-limits} The following items have a limit that varies by your contract. You can check the limit that applies to you in [global nav](../guide/screen-layout) > **Workspace settings** > **Usage**. * Number of members * Number of editors * Number of viewers * Number of guests * Number of groups * Number of teamspaces * Number of connections * Number of synced tables * Number of notebooks * Number of reports * Number of public links * Number of signed embeds * Number of queries * Number of active workflows * Monthly Codatum AI usage --- --- url: 'https://docs.codatum.com/reference/glossary.md' description: A glossary of Codatum terms with links to the detailed specifications --- # Glossary ## Screen {#screen} | Term {.nowrap} | Definition | Details | | --- | --- | --- | | Global nav | The entry points to the main features and settings, at the left edge of the screen | [Screen layout](../guide/screen-layout), [Navigation](../guide/navigation) | | Header | The region at the top of the screen. Holds the title, action buttons, and more | [Screen layout](../guide/screen-layout) | | Left sidebar | The region to the left of the main area. Holds lists, trees, filters, and more | [Screen layout](../guide/screen-layout) | | Main area | The region at the center of the screen. Holds the main content for that screen | [Screen layout](../guide/screen-layout) | | Right sidebar | The region to the right of the main area. Holds detail information, auxiliary panels, and more | [Screen layout](../guide/screen-layout) | ## Feature status {#feature-status} ### Release status | Term {.nowrap} | Definition | | --- | --- | | Preview | A pre-release feature that isn't available to everyone and requires a request for access | | Beta | A pre-release feature that's available to everyone but whose specification isn't finalized | | Deprecated | A feature that will be removed in the future | ### Availability {#optional-feature} | Term {.nowrap} | Definition | | --- | --- | | Optional feature | A feature whose availability depends on your contract | ## Account {#account} | Term {.nowrap} | Definition | Details | | --- | --- | --- | | Account | The unit you use to log in to Codatum. A single account is shared across workspaces | [Account](../account/overview#account-and-user) | | Account settings | Settings scoped to your login account | [Account settings](../account/overview#account-settings) | | User | An account that belongs to a workspace. Includes members and guests | [User](../workspace/administration/user#member-and-guest) | | Member | A Workspace Owner, Workspace Editor, or Workspace Viewer | [User](../workspace/administration/user#member-and-guest) | | Guest | A workspace guest. Can only access limited resources | [User](../workspace/administration/user#member-and-guest) | | PAT | Personal access token | [Personal Access Tokens](../account/settings/pat#issue-token) | ## Workspace and permissions {#workspace-and-permissions} | Term {.nowrap} | Definition | Details | | --- | --- | --- | | Workspace | The unit for managing a set of resources and users together | [Workspace](../workspace/overview) | | Organization | The unit that groups workspaces. Holds the organization name, country, organization owners, and billing information | [Organization settings](../workspace/administration/organization) | | Organization owner | The role that can edit organization settings and invite or remove other organization owners. Can also manage billing and change the plan. Separate from workspace roles | [Organization settings](../workspace/administration/organization#owners) | | Organization settings | The screen for managing the organization name, country, organization owners, and billing information | [Organization settings](../workspace/administration/organization) | | Resource | An object such as a notebook, connection, or teamspace | [Permissions overview](../permissions/overview#terminology) | | Workspace role | A role that every user in a workspace is always assigned exactly one of | [User](../workspace/administration/user#workspace-roles), [Permissions overview](../permissions/overview#terminology) | | Resource role | A role assigned to an individual resource | [Permissions overview](../permissions/overview#terminology) | | Group | A unit for granting permissions to multiple users together | [Group](../workspace/administration/group) | | Teamspace | An area where a specific team jointly manages notebooks and folders | [Teamspace](../workspace/administration/teamspace) | | Access scope | The framework that determines how permissions are evaluated, based on the type of root folder a resource belongs to | [Access scope](../permissions/overview#access-scope) | | Access level | A setting that determines who can use a connection | [Access level](../permissions/resources/connection#access-level) | | Additional notebook permissions | A feature for granting specific users or groups access to a notebook, separate from a folder's base permissions | [Additional notebook permissions](../features/notebook/sharing/additional-permissions/overview) | | Shared folder | The area where notebooks shared through additional notebook permissions appear for the recipient | [Folders](../features/notebook/folder) | | Allowed domain | A setting that allows accounts with an email address at a specified domain to join | [Invitations and joining](../workspace/administration/invite#allowed-domains) | | API key | Credentials tied to a workspace | [API keys](../workspace/access-and-security/api-key) | | Workspace policy | A setting that restricts public link creation or guest invitations at the workspace level | [Workspace policy](../workspace/access-and-security/policy#policy-settings) | | Audit logs | A record of important actions and system events | [Audit logs](../workspace/access-and-security/audit-log) | | MCP | A protocol for connecting AI agents and tools (Model Context Protocol) | [MCP](../workspace/access-and-security/mcp), [Agent connectors](../workspace/codatum-ai/agent-connectors) | ## Data {#data} | Term {.nowrap} | Definition | Details | | --- | --- | --- | | Connection | A connection setting for a data warehouse. The unit for running SQL and syncing table metadata | [Connection](../features/connection/overview) | | Demo connection | A sample connection for trying out the product. Its on-screen connection name is `Demo Connection` | [Demo connection](../features/connection/overview#demo-connection) | | Job label | Metadata that identifies the source of execution on the data warehouse side | [Job label](../features/connection/job-label) | | Catalog | The feature that manages metadata for tables and saved queries | [Catalog](../features/catalog/overview) | | Table metadata sync | The process that brings table and column metadata from a connection into the catalog | [Table metadata sync](../features/catalog/metadata-sync) | | Annotation | A description and tags added to a table or column in the catalog (the on-screen labels are **Description** / **Tags**) | [Annotation](../features/catalog/annotation) | | Tag | A classification label defined at the workspace level and applied to tables, columns, queries, reports, and more | [Tags](../workspace/data-management/tag) | | Query job | A unit of SQL execution history. Used as the basis for popularity and referenced in catalog details | [Query jobs](../features/catalog/overview#query-jobs) | | Popularity | A relative score based on how often a query job is referenced | [Popularity](../features/catalog/overview#popularity) | ## Analysis and sharing {#analysis-and-sharing} | Term {.nowrap} | Definition | Details | | --- | --- | --- | | Quick search | Cross-search across notebooks, tables, and queries | [Quick search](../features/quick-search/overview) | | Query (saved query) | Saved SQL reused within a connection | [Query](../features/saved-query/overview) | | Notebook | Your workspace for analysis, bringing together SQL, charts, and text | [Notebook](../features/notebook/overview) | | Doc page | A notebook page type using a flow-based block editor to lay out SQL, charts, text, and more vertically | [Doc page](../features/notebook/doc-page/overview) | | Grid page | A dashboard-style notebook page type that tiles charts and other content defined on doc pages | [Grid page](../features/notebook/grid-page/overview) | | SQL block | The unit for editing and running SQL, showing results, and creating charts within a notebook | [SQL block](../features/notebook/doc-page/sql-block) | | Chart | A feature that aggregates and processes SQL results and displays them as a graph or table | [Chart](../features/notebook/chart/overview) | | Dimension | The axis a chart uses to group data (shown on screen as **X value**, **Label**, **Hierarchy**, and similar) | [Dimensions and metrics](../features/notebook/chart/concept/dimension-metrics#dimension-metric) | | Metric | The numeric value a chart aggregates (shown on screen as **Y value** and **Value**) | [Dimensions and metrics](../features/notebook/chart/concept/dimension-metrics#dimension-metric) | | In-memory processing | Processing that builds chart data in the browser without issuing new SQL, used when the data source has 1,000 rows or fewer | [In-memory processing](../features/notebook/chart/concept/overview#in-memory-processing) | | Frame | A feature that splits a chart into multiple charts based on the values in a specified column | [Frame feature](../features/notebook/chart/common-settings/frame#frame-feature) | | Parameter | A mechanism that uses an input form at the top of the page and placeholders in SQL to repeat the same analysis with different values | [Parameter](../features/notebook/parameter/overview) | | Explorer | A feature for filtering, aggregating, and pivoting SQL results or chart data sources through a GUI | [Explorer](../features/notebook/explorer) | | Comment | Discussion and feedback attached to the body of a notebook or report. Supports mentions | [Comment](../features/notebook/comment) | | Snapshot | The content of a notebook at the time it was published, as shown through a report, public link, or signed embed | [Sharing](../features/notebook/sharing/overview) | | Report | A feature for publishing and sharing a notebook, for example as read-only | [Report](../features/notebook/sharing/report/overview) | | Public link | A feature that publishes a notebook's content as a snapshot at publish time and lets people view it without logging in | [Public link](../features/notebook/sharing/public-link/overview) | | Signed embed | A feature that embeds a notebook's published content into an external site or app using an API key and token | [Signed embed](../features/notebook/sharing/signed-embed/overview) | | Workflow | A feature that processes query or report steps on a schedule and connects them to follow-up actions such as notifications | [Workflow](../features/workflow/overview) | | Template variable | A mechanism for embedding values such as the results of earlier steps into a workflow's body, prompts, or run conditions (using Liquid syntax) | [Template variables](../features/workflow/template-variables) | | Codatum CLI | A CLI (`cdm`) for operating Codatum from a terminal, CI, or an AI agent | [Codatum CLI](../features/cli/overview) | ## AI {#ai} | Term {.nowrap} | Definition | Details | | --- | --- | --- | | AI agent | A feature that autonomously carries out data analysis and notebook creation and editing based on natural language instructions | [AI agent](../features/ai-agent/overview) | | AI Assistant | A chat-based AI for creating SQL and charts and answering questions. A deprecated legacy feature; new provisioning has been discontinued. Its successor is the AI agent | [AI Assistant](../features/ai-assistant/overview) | | AI Analyst | A way (role) to launch the AI Assistant, for example from the `/` menu on a doc page | [AI Assistant](../features/ai-assistant/overview#roles) | | AI Support | An AI Assistant role for answering questions about how to use Codatum | [AI Assistant](../features/ai-assistant/overview#roles) | | AI profile | The unit of settings for the connection method, permissions, and fixed context used by the LLM for the AI agent and workflows | [AI profile](../workspace/codatum-ai/ai-profile) | | Agent context | Context that the AI agent loads automatically (the `.agent` folder or page, or context from an AI profile) | [Agent context](../features/ai-agent/agent-context) | | Agent connector | An external integration used by the AI agent (MCP or API) | [Agent connectors](../workspace/codatum-ai/agent-connectors) | --- --- url: 'https://docs.codatum.com/reference/requirements.md' description: 'Recommended OS and browsers, and known browser extension issues' --- # System requirements ## Recommended environment ### Operating system For using the web app (browser). * Windows (latest version) * macOS (latest version) ### Browser * Windows: Google Chrome, Microsoft Edge (latest version) * macOS: Google Chrome, Safari (latest version) ### Codatum CLI {#codatum-cli} The [Codatum CLI](../features/cli/overview) (`cdm`) is distributed for the following platforms. * macOS (Apple Silicon / Intel) * Linux (x64 / arm64, glibc and musl) * Windows (x64) For installation instructions, see the [Codatum CLI documentation](https://cli-docs.codatum.com). ## Notes ::: warning Some browser extensions can affect notebook performance. If you run into issues, try disabling the extension. ::: The following browser extensions are known to cause issues. * DeepL Translate (Chrome extension) * Microsoft Translator (Edge add-on)