# Count Learn — Full Content Complete text content from every page on learn.count.co. Use the URL on each entry to link users to the specific page. Website: https://learn.count.co --- # Data Sources Gather all your business knowledge in one place. ## Data warehouses and databases URL: https://learn.count.co/data-sources/database-connection-overview Connect Snowflake, BigQuery, Redshift, Postgres and more. ## Creating a new connection Workspace owners and admins can create a database connection from within a canvas or from the workspace . ## Supported databases Count supports many of the most popular databases, and support for more is coming soon. Information on how to connect to each database can be found on the following pages: - Athena - Azure Synapse - BigQuery - Clickhouse - Databricks - MySQL - PostgreSQL - Redshift - Snowflake - SQL Server ## How the connection works Count is built with security in mind and we have a number of measures in place to protect your data and take care of your database's integrity: - All traffic between your database, Count and any workspace users is fully encrypted using HTTPS and SSL/TLS. - We don't take a copy of your database or alter your tables. - We make sure to protect your database from too much load by only running queries when necessary and limiting the number of results which get returned. More information on our security procedures can be found in our Security overview. ## Connection settings Once you've successfully authenticated your database there are some common settings which apply to all database connections: - Color - set a custom color for this connection. Cells referencing tables in this connection will have this color by default. The connection color can also be overridden per-canvas. - Use DuckDB by default for visuals - with this setting enabled, new visuals created while this connection is selected will execute on the in-memory database in the canvas, rather than on this connection. - Allow agents to run cells automatically - if this setting is enabled, agents will not ask for permission before creating cells or running queries that reference this connection. - Agent context - provide any agent-specific context for this connection. ### Deleting a connection A database connection can be deleted at the bottom of the connection's settings menu. Deleting a database connection will remove it from any projects that reference it. Any cells that rely on this connection will return errors, and will not return results until switched to a different connection. ### Amazon Athena URL: https://learn.count.co/data-sources/database-connection-overview/athena How to connect Athena to Count. ## Click "Connect a database" ## Enter your connection details You'll need: - AWS region of your Athena instance (e.g. us-east-1) - The path to an S3 bucket where outputs will be created (s3://bucket-name/path/to/output) - AWS access key You'll also need to ensure that your firewall accepts requests from the following IP addresses. For eu.count.co workspaces: For app.count.co workspaces: ## Connect Once you hit Connect you will see your connection details including a full list of tables accessible with this connection. ### Azure Synapse URL: https://learn.count.co/data-sources/database-connection-overview/azure-synapse How to connect Azure Synapse to Count ## Click "Connect a database" from your workspace menu ## Enter your connection details You'll need to know: - Host - Port - Database name - Username - Password You'll also need to ensure that your firewall accepts requests from the following IP addresses. For eu.count.co workspaces: For app.count.co workspaces: Connections between Count and your database are encrypted by SSL (TLS). Your database must be configured to use SSL in order for Count to connect. For additional security, you may optionally provide the certificate authority, public client certificate and private client key (in PEM format). ## Connect Once you hit Connect you will see your connection details including a full list of tables accessible with this connection. ## Troubleshooting If you're having trouble connecting, check the error message returned at the top of the Connection page against the table below for a possible fix. ## SSL certificate errors If you see a connection error complaining about "self signed certificates", it's likely that there's an issue verifying the SSL certificates issued by your database server against the host parameter of your sever details. This can happen for several reasons - You are using manually created self signed certificates, in which case it's not possible to verify the identity of your server - The database server does support verifiable certificates (e.g. some Heroku systems) - The certificates are issued by the provider of your managed database server (e.g. Digital Ocean, GCP) and the host parameter is an IP address If anyone of these is the case, the connection issue can usually be resolved either by - downloading your database server Certificate Authority (CA) file, usually given in PEM format, and uploading to the "Advanced" section of the connection setup - or, activating the "Trust server certificate" in the "Advanced" section of the connection setup Why don't I need to upload the CA when connecting to other products? You may be wondering why you're able to connect automatically to clients such as mssql-cli or other web-based BI tools, but Count may require you to upload the CA certificate. In the Enable Encrypted Connections to the Database Engine section of the SQL Server documentation, it clarifies that "The client must be able to verify the ownership of the certificate used by the server. If the client has the public key certificate of the certification authority that signed the server certificate, no further configuration is necessary. ... If the server certificate was signed by a public or private certification authority for which the client does not have the public key certificate, you must install the public key certificate of the certification authority that signed the server certificate." If the server certificate was signed by a public or private CA, uploading the CA file manually to Count allows the communication to happen safely, ensure maximal protection against eavesdropping and MITM attacks. What does "Trust server certificate" mean? If you are unable to obtain a copy of your database CA (e.g. some Heroku systems), the only way to initiate encrypted communication with your database is to trust that the certificate sent by the server is correct (SSL mode "require"). This ensures full protection against eavesdropping, but not against MITM attacks. Count will only use this mode of communication if you activate the "Trust server certificate" in the "Advanced" section of the connection setup. You should consult your database administrator to confirm that this setting is appropriate for your system. If another product is able to connect automatically without the above worrying about server certificates, it may be worth checking what SSL mode they are using for communication, and whether this is sufficient for your needs. ### BigQuery URL: https://learn.count.co/data-sources/database-connection-overview/bigquery How to connect BigQuery to Count. ## Enter your connection details You'll need: - The Project ID of the BigQuery instance - A service account key in JSON format for a service account with the following permissions The quickest way to grant these permissions is to assign the service account the roles BigQuery Data Viewer and BigQuery Job User. ## Dataset access By default, you are able to query any dataset in the BigQuery project (limited by the supplied credentials). You are also able to query datasets in other BigQuery projects (as long as the credentials have access to those projects), but datasets in other BigQuery projects will not appear in the Count UI. If table access is restricted within a Count project, then canvases in that project will be unable to query tables outside of this BigQuery project. ## BigQuery Storage API When running queries with the default row limit disabled, it may take a long time to extract large result sets from BigQuery. In this case you may want to enable the BigQuery Storage API, which uses an alternative method to extract results more quickly for these queries. To use this API, you'll need to grant your service account the additional permissions: You will also need to enable this in Count: - Click on your database in the left-hand panel of your Workspace homepage - Select 'Manage connections' - Toggle on 'Enable BigQuery Storage API' Use of the BigQuery Storage API may result in a small increase in your BigQuery costs. If your workspace has been granted an increase in the default query response size limit, you'll need to enable the BigQuery Storage API for this increase to take effect. ## Processed data estimations If automatic execution for a BigQuery cell has been disabled, then an estimate of the data that will be processed by the query is shown in the cell body: ## Troubleshooting The most common issue when connecting to BigQuery data is getting the service account permissions correct. Double-check the service account permissions with the list above. Additionally, if your BigQuery datasets contain tables that reference External datasources, please check that the service account has viewer access to the files/buckets/drives where the datasources reside. ### Out of Memory Errors If you are connecting to a BigQuery project with many tables, you may see an out-of-memory error when you try to connect. To resolve this, you can limit the datasets you want to connect to using the following steps: - Create a new service account with the BigQuery Job User permission 2. In the BigQuery console, go the dataset you want to assign permission to, and click Share Dataset (instructions here). 3. Add the service account email to the dataset with the BigQuery Data Viewer permission: 4. Repeat this for any other datasets you want this service account to have access to. 5. Add the service account key to Count and you'll only access the tables for the datasets you've specifically chosen. ### IP Whitelisting You may need to allow connections to the following IP addresses for Count to establish a connection: For eu.count.co workspaces: For app.count.co workspaces: ### ClickHouse URL: https://learn.count.co/data-sources/database-connection-overview/clickhouse Connect Clickhouse to Count: enter basic DB details, allow listed IPs, and use SSL/TLS for secure, encrypted access. ## Click "Connect a database" ## Enter your connection details To connect your database, you'll need to enter: - Display name - Host - Port - Database name - Username - Password You'll also need to ensure that your firewall accepts requests from the following IP addresses. For eu.count.co workspaces: For app.count.co workspaces: Connections between Count and your database are encrypted by SSL (TLS). Your database must be configured to use SSL in order for Count to connect. ## Connecting via SSH Count supports SSH connections to your ClickHouse database, via a bastion host. To connect via SSH you must have - a bastion host in your VPC which can connect to your private database - whitelisted Count's server IPs so that we can securely connect to your bastion host VM - details for how to connect to your bastion host, including the host, port, user and a private SSH key. Details for how to set up a bastion host can be found in your cloud service provider's documentation. On Count, you can additionally secure your traffic by specifying an SSH host and the algorithm used to generate it. Our servers will check this value against that provided by your VM on connection, helping to verify its identity. This information can be obtained when generating the SSH key pair. On AWS, this information is available in your EC2 instance System logs; you should see a entry in the log with a list of SSH host key keys Select an algorithm and verification key pair and enter into the details in the above form. ### Databricks URL: https://learn.count.co/data-sources/database-connection-overview/databricks How to connect Databricks to Count. ## Click "Connect a database" ## Enter your connection details You'll need: - Hostname and path of your Databricks cluster You'll also need to ensure that your firewall accepts requests from the following IP addresses. For eu.count.co workspaces: For app.count.co workspaces: Use this guide to obtain your hostname and path Use this guide to obtain an access token ## Authentication options ### Access token To connect using an access token, select this option from the Authentication options dropdown, enter the required values and click Connect. ### OAuth To connect using OAuth, you must first create a custom OAuth application in your Databricks account console. - Give a sensible name for the connection (e.g. Count-OAuth) and select "All APIs" for the Access scopes. - Set the Redirect URL to be https://app.count.co/connection-oauth (or https://eu.count.co/connection-oauth for EU tenancy). - By default, the Refresh token TTL is set to 7 days. Every 7 days, Count's connection will need to be re-authorized (see below) to re-enable to the connection to Databricks. Count recommends a value between 1 week (10080) and 90 days (129600) to avoid the need to re-authorize too often. - Once created, make a note of the Client ID and the Client secret, as these will be required to create the connection in Count. - Navigate to your Count workspace, click Connect a database, and choose Databricks. - Select OAuth in the Authentication options dropdown, and enter your Host, and the Client ID obtained in step 3. - When you click Authorize, you will be redirected to your usual Databricks login flow (including an MFA required by your account). - Once you have logged successfully authorized on the Databricks side, you will be automatically redirected back to your Connect to Databricks page in Count. You'll now be asked for the value of the Client secret obtained in step 3, your Database name, and any other optional properties you wish to configure, including Refresh token validity (see below). The initial code retrieved from Databricks has a very short lifetime (1 minute). Please make sure you complete this step within that time. - Click Connect to complete the connection. Set the value of Refresh token validity in your Count Databricks connection to the value of 60 * Refresh token TTL (i.e. the value of the TTL in seconds) to receive email reminders of when re-authorization is due. If an error is encountered during step 7, you will need to re-authorize once again (steps 5 - 7). Re-authorization The refresh token obtained by Count from Databricks during step 7 enables Count to obtain a short lived (60 minutes by default) session token from Databricks to, amongst other things, run queries against your database. This refresh token itself has an expiry given by the value of Refresh token TTL set above. The connection will therefore need to be re-authorized whenever it is due to expire. Navigate to your Databricks connection settings page, and click Re-authorize to regenerate a new refresh token (steps 5 - 7 above). ## OAuth Service Principal To connect using OAuth Service Principal: - Create a Service Principal in the Databricks account console - Assign workspace level permissions to that Service Principal - Create an OAuth secret for that Service Principal, making a note of the Client ID and Client Secret. - Enter your Host, Path, Client Id, and Client Secret (and other optional parameters) then click connect. ## Connect Once you hit Connect you will see your connection details including a full list of tables accessible with this connection. ## Troubleshooting The most common issue common issue when connecting to a Databricks cluster is that the warehouse is unresponsive if it has stopped due to inactivity. Count's connecting and querying logic will retry every 10 seconds for 3 minutes. If Count is still unable to connect to your cluster after this time, a 503 error will return. Ensure that your warehouse is running and available to accept connections from the Count IP addresses (see above) and retry the connection in Count. ## Limitations ### BigInt The BigInt data type in Databricks can accommodate integers in the range -2^63 -> 2^63 -1 . Due to a limitation in the Databricks client, Count can accommodate a reduced range of -2^53 -> 2^53 -1 for this data type. Values outside of this reduced range will be displayed as null values. ### VALUES clause Count uses a reduced parse to determine which cells are referenced in your SQL statements. Databrick's SELECT statement and querying syntax is more flexible than those of other databases. As a result, there is an unresolvable ambiguity in Count's reduced parse for statements of the form SELECT * FROM VALUES 1, 2, 3 Running a SQL statement similar to this will result in an error similar to "Unexpected number", "Unexpected literal", etc. The workaround for this issue is to parenthetise the row values in the VALUES clause, e.g. SELECT * FROM VALUES (1), (2), (3) ### SQL Server URL: https://learn.count.co/data-sources/database-connection-overview/sql-server How to connect Microsoft SQL Server to Count ## Click "Connect a database" ## Enter your connection details You'll need to know: - Host - Port - Database name - Username - Password You'll also need to ensure that your firewall accepts requests from the following IP addresses. For eu.count.co workspaces: For app.count.co workspaces: Connections between Count and your database are encrypted by SSL (TLS). Your database must be configured to use SSL in order for Count to connect. For additional security, you may optionally provide the certificate authority, public client certificate and private client key (in PEM format). ## Connect Once you hit Connect you will see your connection details including a full list of tables accessible with this connection. ## Troubleshooting If you're having trouble connecting, check the error message returned at the top of the Connection page against the table below for a possible fix. ## SSL certificate errors If you see a connection error complaining about "self signed certificates", it's likely that there's an issue verifying the SSL certificates issued by your database server against the host parameter of your sever details. This can happen for several reasons - You are using manually created self signed certificates, in which case it's not possible to verify the identity of your server - The database server does support verifiable certificates (e.g. some Heroku systems) - The certificates are issued by the provider of your managed database server (e.g. Digital Ocean, GCP) and the host parameter is an IP address If anyone of these is the case, the connection issue can usually be resolved either by - downloading your database server Certificate Authority (CA) file, usually given in PEM format, and uploading to the "Advanced" section of the connection setup - or, activating the "Trust server certificate" in the "Advanced" section of the connection setup Why don't I need to upload the CA when connecting to other products? You may be wondering why you're able to connect automatically to clients such as mssql-cli or other web-based BI tools, but Count may require you to upload the CA certificate. In the Enable Encrypted Connections to the Database Engine section of the SQL Server documentation, it clarifies that "The client must be able to verify the ownership of the certificate used by the server. If the client has the public key certificate of the certification authority that signed the server certificate, no further configuration is necessary. ... If the server certificate was signed by a public or private certification authority for which the client does not have the public key certificate, you must install the public key certificate of the certification authority that signed the server certificate." If the server certificate was signed by a public or private CA, uploading the CA file manually to Count allows the communication to happen safely, ensure maximal protection against eavesdropping and MITM attacks. What does "Trust server certificate" mean? If you are unable to obtain a copy of your database CA (e.g. some Heroku systems), the only way to initiate encrypted communication with your database is to trust that the certificate sent by the server is correct (SSL mode "require"). This ensures full protection against eavesdropping, but not against MITM attacks. Count will only use this mode of communication if you activate the "Trust server certificate" in the "Advanced" section of the connection setup. You should consult your database administrator to confirm that this setting is appropriate for your system. If another product is able to connect automatically without the above worrying about server certificates, it may be worth checking what SSL mode they are using for communication, and whether this is sufficient for your needs. ### MySQL URL: https://learn.count.co/data-sources/database-connection-overview/mysql How to connect MySQL to Count. ## Click "Connect a database" ## Enter your connection details You'll need to know - the Host - Port - Database name - Username - Password You'll also need to ensure that your firewall accepts requests from the following IP addresses. For eu.count.co workspaces: For app.count.co workspaces: Connections between Count and your database are encrypted by SSL (TLS). Your database must be configured to use SSL in order for Count to connect. For additional security, you may optionally provide the certificate authority, public client certificate and private client key (in PEM format). ## Connect Once you hit Connect you will see your connection details including a full list of tables accessible with this connection. ## Troubleshooting If you're having trouble connecting, check the error message returned at the top of the Connection page against the table below for a possible fix. ### SSL certificate errors If you see a connection error complaining about "self signed certificates", it's likely that there's an issue verifying the SSL certificates issued by your database server against the host parameter of your sever details. This can happen for several reasons - You are using manually created self signed certificates, in which case it's not possible to verify the identity of your server - The database server does support verifiable certificates (e.g. some Heroku systems) - The certificates are issued by the provider of your managed database server (e.g. Digital Ocean, GCP) and the host parameter is an IP address If anyone of these is the case, the connection issue can usually be resolved either by - downloading your database server Certificate Authority (CA) file, usually given in PEM format, and uploading to the "Advanced" section of the connection setup - or, activating the "Trust server certificate" in the "Advanced" section of the connection setup ### Why don't I need to upload the CA when connecting to other products? You may be wondering why you're able to connect automatically to clients such as mysql client or other web-based BI tools, but Count may require you to upload the CA certificate. In the Configuring MySQL to Use Encrypted Connections section of the MySQL documentation, it clarifies that there are 6 modes of SSL support. By default, Count communicates with your database server by using the most secure method of communication, "verify-full", which provides full protection against eavesdropping and MITM attacks. This method requires full verification of the CA , which may not be possibly if the server does not issue a root certificate, or if the domain of the certificate and the database server host address do not match (as is usually the case where the host parameter is an IP address). In that case, uploading the CA file manually to Count allows the communication to happen safely with the mode "verify-ca", using your uploaded certificate to ensure maximal protection against eavesdropping and MITM attacks. ### What does "Trust server certificate" mean? If you are unable to obtain a copy of your database CA (e.g. some Heroku systems), the only way to initiate encrypted communication with your database is to trust that the certificate sent by the server is correct (SSL mode "require"). This ensures full protection against eavesdropping, but not against MITM attacks. Count will only use this mode of communication if you activate the "Trust server certificate" in the "Advanced" section of the connection setup. You should consult your database administrator to confirm that this setting is appropriate for your system. If another product is able to connect automatically without the above worrying about server certificates, it may be worth checking what SSL mode they are using for communication, and whether this is sufficient for your needs. ### PostgreSQL URL: https://learn.count.co/data-sources/database-connection-overview/postgresql How to connect PostgreSQL to Count ## Click "Connect a database" ## Enter your connection details To connect your database, you'll need to enter: - Host - Port - Database name - Username - Password You'll also need to ensure that your firewall accepts requests from the following IP addresses. For eu.count.co workspaces: For app.count.co workspaces: Connections between Count and your database are encrypted by SSL (TLS). Your database must be configured to use SSL in order for Count to connect. For additional security, you may optionally provide the certificate authority, public client certificate and private client key (in PEM format). ## Connect Once you hit Connect you will see your connection details including a full list of tables accessible with this connection. ## Connecting via Heroku To connect your Heroku-hosted PostgreSQL database to Count, there a few additional things to consider. Some Heroku systems do not support verifiable certificates, making Count's preferred method of connection impossible. (see the Why don't I need to upload the CA when connecting to other products? section below for more details). To enable secure Heroku connections in Count there are two options: - Heroku users could use mutual TLS for a more secure connection, but this is a paid service. (see more here) - Enable the 'Trust Server Certificate' button upon connecting to Count (see the What does "Trust server certificate" mean? section below for more details) ## Connecting via SSH (beta) Count now supports SSH connections to your PostgreSQL database, via a bastion host. This feature is in beta. Please contact Count support to request access to this feature. To connect via SSH you must have - a bastion host in your VPC which can connect to your private database - whitelisted Count's server IPs so that we can securely connect to your bastion host VM - details for how to connect to your bastion host, including the host, port, user and a private SSH key. Details for how to set up a bastion host can be found in your cloud service provider's documentation. On AWS, the documentation for connecting to an RDS instance via a bastion host can be found here. On Count, you can additionally secure your traffic by specifying an SSH host and the algorithm used to generate it. Our servers will check this value against that provided by your VM on connection, helping to verify its identity. This information can be obtained when generating the SSH key pair. On AWS, this information is available in your EC2 instance System logs; you should see a entry in the log with a list of SSH host key keys Select an algorithm and verification key pair and enter into the details in the above form. ## Advanced settings The PostgreSQL connection in Count supports a number of advanced settings: - Max concurrent connections - Set the maximum number of simultaneous connections between Count and your database. If your database has a lower limit than the value set here, then the lower limit will take precedence. - Query timeout - queries executed from Count will be automatically aborted after this length of time. ## Troubleshooting If you're having trouble connecting, check the error message returned at the top of the Connection page against the table below for a possible fix. ### SSL certificate errors If you see a connection error complaining about "self signed certificates", it's likely that there's an issue verifying the SSL certificates issued by your database server against the host parameter of your sever details. This can happen for several reasons - You are using manually created self signed certificates, in which case it's not possible to verify the identity of your server - The database server does support verifiable certificates (e.g. some Heroku systems) - The certificates are issued by the provider of your managed database server (e.g. Digital Ocean, GCP) and the host parameter is an IP address If any one of these is the case, the connection issue can usually be resolved either by - downloading your database server Certificate Authority (CA) file, usually given in PEM format, and uploading to the "Advanced" section of the connection setup - activating the "Trust server certificate" in the "Advanced" section of the connection setup Why don't I need to upload the CA when connecting to other products? You may be wondering why you're able to connect automatically with clients such as psql or other web-based BI tools, but Count asks to upload the CA certificate. In the SSL Support section of the PostgreSQL documentation, it clarifies that there are 6 modes of SSL support. By default, Count communicates with your database server using the most secure method of communication, "verify-full", which provides full protection against eavesdropping and MITM attacks. This method requires full verification of the CA , which may not be possible if the server does not issue a root certificate, or if the domain of the certificate and the database server host address do not match (as is usually the case where the host parameter is an IP address). In that case, uploading the CA file to Count allows the communication to happen safely with the mode "verify-ca", using your uploaded certificate to ensure maximal protection against eavesdropping and MITM attacks. What does "Trust server certificate" mean? If you are unable to obtain a copy of your database CA (e.g. some Heroku systems), the only way to initiate encrypted communication with your database is to trust that the certificate sent by the server is correct (SSL mode "require"). This ensures full protection against eavesdropping, but not against MITM attacks. Count will only use this mode of communication if you activate the "Trust server certificate" in the "Advanced" section of the connection setup. You should consult your database administrator to confirm that this setting is appropriate for your system. If another product is able to connect automatically without the above considerations of server certificates, it may be worth checking what SSL mode they are using for communication, and whether this is sufficient for your needs. ### Redshift URL: https://learn.count.co/data-sources/database-connection-overview/redshift How to connect Redshift to Count ## Click "Connect a database" ## Enter your connection details To connect your database, you'll need to enter: - Host - Port - Database name - Username - Password You'll also need to ensure that your firewall accepts requests from the following IP addresses. For eu.count.co workspaces: For app.count.co workspaces: Connections between Count and your database are encrypted by SSL (TLS). Your database must be configured to use SSL in order for Count to connect. ## Connect Once you hit Connect you will see your connection details including a full list of tables accessible with this connection. ## Connect via SSH (beta) Count now supports SSH connections to your redshift database, via a bastion host. This feature is in beta. Please contact Count support to request access to this feature. To connect via SSH you must have - a bastion host in your VPC which can connect to your private database - whitelisted Count's server IPs so that we can securely connect to your bastion host VM - details for how to connect to your bastion host, including the host, port, user and a private SSH key. Details for how to set up a bastion host can be found in your cloud service provider's documentation. On AWS, the documentation for connecting to a redshift instance via a bastion host can be found here. On Count, you can additionally secure your traffic by specifying an SSH host and the algorithm used to generate it. Our servers will check this value against that provided by your VM on connection, helping to verify its identity. This information can be obtained when generating the SSH key pair. On AWS, this information is available in your EC2 instance System logs; you should see a entry in the log with a list of SSH host key keys Select an algorithm and verification key pair and enter into the details in the above form. ## Advanced settings The Redshift connection in Count supports a number of advanced settings: - Enable case-sensitive identifiers - read more about the impact of this setting here. - Max concurrent connections - Set the maximum number of simultaneous connections between Count and your database. If your database has a lower limit than the value set here, then the lower limit will take precedence. - Query timeout - queries executed from Count will be automatically aborted after this length of time. ## Troubleshooting If you're having trouble connecting, check the error message returned at the top of the Connection page against the table below for a possible fix. ### Schema/tables are missing from my connection If you do not see tables listed in Count that you expect, please check that the permissions for the user account used by Count are configured correctly. To test which tables your credentials have access to, you can try running a query from a Count cell like: You should also confirm: - The user account used for Count is covered by any IP whitelisting rules you have established. - The user account used for Count has been granted usage permissions on any schemas you require. The permissions need to be granted by an account with schema ownership. Some permissions may need a new session before they take effect. Count may retain a session for some time after it is last used, so waiting a little before refreshing schema may help. ### SSL certificate errors What does "Trust server certificate" mean? If you are unable to obtain a copy of your database CA (e.g. some Heroku systems), the only way to initiate encrypted communication with your database is to trust that the certificate sent by the server is correct (SSL mode "require"). This ensures full protection against eavesdropping, but not against MITM attacks. Count will only use this mode of communication if you activate the "Trust server certificate" in the "Advanced" section of the connection setup. You should consult your database administrator to confirm that this setting is appropriate for your system. If you are having trouble connecting, reach out to us to schedule a help session ## Limitations Assert A commonly encountered idiosyncrasy for Redshift users is the Assert error. A query submitted to Redshift can result in an Assert error for a number of reasons, one of them being a bug in the Redshift itself. Below is a list of cases and workarounds for how to amend queries returning Assert errors. Multiple subqueries in WHERE clause The following query may result in an Assert error due to the subqueries in the WHERE clause: Fix 1 - use a CROSS JOIN instead of multiple subqueries Fix 2 - use a jinja template ### Snowflake URL: https://learn.count.co/data-sources/database-connection-overview/snowflake How to connect Snowflake to Count. ## Click "Connect a database" ## Enter your connection details To enable Count to connect to your Snowflake database, you'll need your full Snowflake account identifier. You can find your account identifier in the Account Details section of the Snowflake web console, or you can run this SQL query: SELECT CURRENT_ORGANIZATION_NAME() || '-' || CURRENT_ACCOUNT_NAME(); For more information about finding account identifiers, see the Snowflake documentation here. ## Authentication options (1) Key-pair auth To connect using key-pair auth, select this option from the Authentication options dropdown, enter the required values and click Connect. Before starting, you'll need to generate a private and public key in Snowflake and configure your Snowflake users. See the steps to follow for this in Snowflake's documentation. A few points to note: - We currently only support the RSA256 algorithm for generating keys. - We support both encrypted and unencrypted private keys. - For encrypted private keys, the passphrase must be provided. (2) Username and password To connect using username and password, select this option from the Authentication options dropdown, enter the required values and click Connect. (3) OAuth To connect using OAuth, you must first create a Snowflake Security Integration. To create a Snowflake Security Integration you will need to be a Snowflake account administrator (users with the ACCOUNTADMIN role) or have a role with the global CREATE INTEGRATION privilege. - Navigate to the Snowflake UI console (or other Snowflake client) - Create a new SQL worksheet - Create the Snowflake Security Integration by running the following SQL command Notes: - OAUTH_ISSUE_REFRESH_TOKENS (in seconds) is set to 30 days in the above statement. Every 30 days, Count's connection will need to be re-authorized (see below) to re-enable to the connection to Snowflake. Count recommends a value between 1 week (604800) and 90 days (7776000) to avoid the need to re-authorize too often - Once created, retrieve the OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET parameters using the following statement - Navigate to your Count workspace, click Connect a database, and choose Snowflake. - Select OAuth in the Authentication options dropdown, and enter your Account, the value obtained in step 4 for the OAUTH_CLIENT_ID. By default, the BLOCKED_ROLES_LIST also includes the roles ACCOUNTADMIN, SECURITYADMIN, and ORGADMIN, which means users with only those roles cannot consent to using the security integration, and the authorization step on Snowflake will fail. If the person authorizing the connection has one of these roles, please ensure that they are also assigned a reduced privilege role (e.g. ANALYST) and enter that as the value for Role. - When you click Authorize, you will be redirected to your usual Snowflake login flow. Please not that certain roles are blocked from authorizing using this flow. Please contact Snowflake support should you have further questions. - Once you have logged successfully authorized on the Snowflake side, you will be automatically redirected back to your Connect to Snowflake page in Count. You'll now be asked for the value of the OAUTH_CLIENT_SECRET obtained in step 4, your Database name, and any other optional properties you wish to configure, including the Refresh token validity (see below). Click Connect to complete the connection. Set the value of Refresh token validity in your Count Snowflake connection to the value of OAUTH_REFRESH_TOKEN_VALIDITY to receive email reminders of when re-authorization is due. Re-authorization The refresh token obtained by Count from Snowflake during step 8 enables Count to obtain a short lived (10 minutes) session token from Snowflake to, amongst other things, run queries against your database. This refresh token itself has an expiry given by the value of OAUTH_REFRESH_TOKEN_VALIDITY set above. The connection will therefore need to be re-authorized whenever it is due to expire. Navigate to your Snowflake connection settings page, and click Re-authorize to regenerate a new refresh token (steps 6 - 8 above). ## Connect Once you have connected you will see your connection details including a full list of tables accessible with this connection. ## Database access By default, you are able to query any table in the Snowflake database (limited by the supplied credentials). You are also able to query tables in other databases as long as the credentials have access to those databases, though they do not appear in the Count UI. If table access is restricted within a Count project, then canvases in that project will be unable to query tables outside of this Snowflake database. ## Advanced settings The Snowflake connection in Count supports a number of advanced settings: - Max concurrent connections - Set the maximum number of simultaneous connections between Count and your database. If your database has a lower limit than the value set here, then the lower limit will take precedence. - Query timeout - queries executed from Count will be automatically aborted after this length of time. ## Troubleshooting The most common issue when connecting to Snowflake is getting the account name correct. You can find more information about your account name in the Snowflake documentation. If you have a network policy defined which whitelists connections based on IP address, you may need to allow connections to the following IP addresses for Count to establish a connection: For eu.count.co workspaces: For app.count.co workspaces: ### Connection settings URL: https://learn.count.co/data-sources/database-connection-overview/connection-settings Configure how your data connections are represented in Count. In Count, connections are where data sources are defined and shared. From the connections page it is possible to: - View all projects referencing this connection. - View workspace members with access to this connection. - View database tables accessible from this connection - Manage connection credentials and settings ## Manage connection From the connection page, select Manage connection to view connection settings. Only workspace admins and owners can see connection settings. If a connection is shared with another workspace member, they will not be able to access this page. From this page it is possible to: - Change the display name of the connection in Count - Change the description of the connection in Count - Update the connection credentials - Refresh the connection schema - Add and edit connection-level AI Agent context - Delete the connection ### Refresh database schema URL: https://learn.count.co/data-sources/database-connection-overview/refresh-database-schema When your database schema changes, make sure those changes are reflected in Count. If the tables available to Count through its database credentials change, then you will need to ask Count to fetch the latest schema to see those changes reflected your workspace. ## Option 1: from the connection settings Select your connection from the workspace home page, then Manage connection. The option to refresh the schema is available near the bottom of the page. If your database contains a large number of tables, Count may not import all of them. To reduce the number of tables that Count attempts to import, an optional filter may be applied that is applied to the schema of the table. There are two options for the form of this filter. - Javascript regular expression. This regular expression is applied to the schema of each row of table metadata streamed to Count's servers. For example, to only fetch schema that begin with the text "production", the filter should be ^production. To only fetch schema that end with the text "_prod", the filter should be _prod$. - Database native expression. This regular expression is applied to the query executed on your database to retrieve the table metadata. As this is applied to the query, not the table metadata stream, this may give improved performance when executing database schema refreshes. However, the regex itself is database dependent (see table below) and may not be as expressive as the JavaScript filter above. The table below, shows how each filter is implemented. To test your regular expression, you may want to use a free tool such as RegExr. A common difference between JavaScript regex and Database native regexes is that the former will match on substring matches by default, but Database native regexes will match the full string. To perform partial matches in Database native regex, you will need to explicitly add a wildcard parameter (e.g. %). ### Database regex engine ## Option 2: from a canvas You can also refresh the schema directly from the canvas by clicking the refresh icon in the data bar ## Automatic schema refresh Count can automatically refresh your database schema on a schedule to ensure your metadata stays in sync without manual intervention. (Available for paid plans only.) By default, this automatic refresh is scheduled for 4am UTC. You can configure a different schedule or disable this feature entirely by selecting Manage connection in the connection homepage. ### dbt integration URL: https://learn.count.co/data-sources/database-connection-overview/dbt-integration Import your dbt models into Count dbt is an open-source tool for transforming data, helping data engineers build and define a DAG of SQL queries called models. By adding dbt models as cells, the Count canvas becomes a natural place to collaboratively explore, visualise, and develop your dbt models. ## dbt Cloud and Core integration Count supports dbt Cloud and dbt Core integrations. Learn how to connect to each in the following pages: dbt Cloud dbt Core ## Video tutorials Learn more about how the dbt integration in Count works in the following videos: - Feature overview - Connecting dbt - Adding models to the canvas - Committing changes to GitHub ## Why import dbt metadata? With a dbt integration your database tables in Count are annotated with dbt model and test metadata, allowing you to import raw and compiled code with lineage intact. Count compiles your raw code live, allowing you to swap model references for cells and vice-versa. This simple but powerful feature enables lots of helpful workflows. For example, you may: - Import a database table with all upstream models in one click. - Explode a model into its component CTEs for better debugging and comprehension. - Execute models against other databases - for example, staging and production environments. - Prototype and iterate models live with the data team, then export dbt-ready model files. ## Viewing dbt metadata Once a dbt integration is created, a dbt icon appears in the table pane when hovering over any database table or view that is associated with a source or model (plus any ephemeral models). Clicking this icon opens a metadata pane that exposes additional information from your dbt project, including documentation and test results. ## Importing models The Add to canvas button exposes options for adding models and sources to the canvas: The different options here determine how the model is added and subsequently executed: ### Jinja / Compiled The Jinja option adds the model using the raw code from the original .sql file that defines it. The Compiled option adds the model as plain SQL as compiled by dbt. This option is available if your dbt artifacts contain compiled SQL. Compiled SQL may be preferable if your model compilation requires information that is not available in Count, for example any private or local environment variables passed to dbt in another environment. ### Explode cells If enabled, models are exploded into CTEs before being added to the canvas. When a model has been exploded, the exploded cells are wrapped in a frame. The cell containing the base SELECT statement from the model will be annotated with a dbt icon, while the other cells formed from the CTEs will not. ### Upstream / downstream levels By increasing the values here, it is possible to import additional upstream and downstream models at the same time as this one - the number of models that will be added is shown in the button below. Leaving both values at zero will import only the current model. For example, selecting 1 upstream level and 2 downstream levels for model model is equivalent to the dbt select command: ## Model cells When a cell is connected to a source with dbt enabled, then it will be possible to mark that cell as a dbt model using the controls in the right sidebar: If a cell is marked as a model: - A dbt icon appears in the header of the cell. - When exporting SQL + Jinja, references to that cell default to ref() rather than SQL, with cells further upstream not included. - If the dbt Core integration is connected to GitHub, then changes to these cells are interpreted as changes to dbt model files. ## How the ref() macro works The ref() macro is one of several macros that are built-in to dbt and available in Count with some additional functionality. When using this macro, any references to upstream models will be compiled to: - A Count cell reference if a cell with that name exists - A database identifier if a dbt model with that name exists, and is present in the database - A CTE if an ephemeral dbt model with that name exists This is a very helpful feature when developing models, as Count cells can act as temporary scratchpads that can override your existing model definitions. To switch between referring to a Count cell or a database table, just rename or delete the cell. To quickly view how a reference is compiled, hover over it to view either the compiled SQL or a link to the cell: If a cell is deleted, all cells containing a ref() that reference that cell will be recompiled, and revert back to referencing the full database identifier. ## How Jinja compilation works Count reads your dbt artifacts and uses that information to compile your Jinja-SQL code directly in your browser. This ensures that compilation is quick, helping you to explore and iterate your models rapidly. Because some dbt macros require executing arbitrary SQL, compilation involving complex dbt functionality is currently disabled for canvas viewers. When opening a canvas, if you're a canvas editor the relevant dbt artifacts will be downloaded by your browser. Once the artifacts have been downloaded and processed in the background, your models and macros will become available in autocompletions: In addition, Count makes available a subset of common dbt functionality, including access to cell results and formatting using native dbt macros: dbt macros that access cell results will error if that cell is currently being executed or compiled. In this case, re-compile the cell once results are available using the Run cell button. For compatibility with existing dbt models and macros, it is also possible to execute queries during the compilation phase of cell execution. We would suggest avoiding this approach where possible, as it is not yet (and may never be) fully integrated with Count's reactive cell execution framework. Any queries executed during compilation are authorised and validated in the same way as any other cell query in Count, so are limited to SELECT statements. ## Troubleshooting Compilation fails for another member of my team Currently, canvas viewers can only compile cells which contain: • Generic Jinja functionality - for example, for-loops, set expressions, inline macros • Uses of the ref() macro which refer to other cells • Uses of the Count cells variable If more complex dbt functionality is encountered, compilation will fail and a warning will be displayed in the corner of the cell: This is a temporary security measure which will be lifted soon once dbt support in Count is expanded more generally. Count fails to compile my Jinja-SQL The Count dbt integration is designed to complement rather than replace your existing dbt workflows, so does not support the full range of dbt functionality. For example, any macros that involve executing queries that write to your database will fail, and any supporting introspective macros may also fail. If you encounter a failure to compile a macro that you believe should be supported, please contact support using the in-app chat. You can always force a re-compilation by clicking the Run cell button. Count failed to import my metadata This may occur if the version of dbt in your project produces artifacts which are not yet understood by Count - for example, if the dbt version is too new or too old. While these errors will be reported automatically, please contact support using the in-app chat if you think that your metadata should have been imported correctly. I don't see all of my jobs / my runs don't show any artifacts This can occur if you are using a service token that was generated while your dbt Cloud account was unpaid. To fix this issue, after upgrading to a paid dbt Cloud account, please generate a new service token and update the dbt Cloud credentials in Count. #### dbt Core integration URL: https://learn.count.co/data-sources/database-connection-overview/dbt-integration/dbt-core-integration Import your dbt Core models into Count Use our tutorial videos, or follow the step-by-step guide on how to set up and manage your dbt Core connection. ## Video tutorial overview This tutorial will provide an introduction to dbt Core integration, highlighting a number of key features including pulling directly from GitHub and working with BigQuery tables. The following tutorials will provide walk through getting you started. [Video: dbt Core overview] [object Object],[object Object] ## Tutorial 1 Learn to connect dbt Core integration to access connection settings, configure profiles.yaml securely, and verify setup through metadata analysis and artifacts verification. [Video: dbt Core Tutorial 1 - Getting Connected] [object Object] ## Tutorial 2 Learn to add dbt models to canvas. Drag tables, compile code, view SQL, manage dependencies, and explode models into cells. [Video: dbt Core Tutorial 2 - Adding Models] ## Tutorial 3 In the final tutorial, learn GitHub integration with dbt Core, create new models, use proper syntax with Jinja, and commit changes to BigQuery. [Video: dbt Core Tutorial 3 - Committing Changes] ## Step-by-step guide In an existing database connection, select Manage connection, then select the dbt tab and choose the dbt Core source. You can import your dbt Core models by installing the Count GitHub app, and/or by executing dbt locally and uploading the manifest.json artifact file. ### Uploading manifest.json Clicking the Upload artifact button will display an upload form, where the required fields are - Project name - the name of this dbt project. Any macros with this package name will be available in the global scope within Count cells. - Manifest file - a manifest.json artifact with the correct format - Manifest identifier - an arbitrary name to refer to this manifest by in Count Once one or more manifests have been uploaded, available artifacts will be listed below. ### Connecting to GitHub The Count GitHub integration simplifies the process of retrieving dbt Core metadata, and also allows committing changes back to your repository. To connect to GitHub, you'll be prompted to install the Count GitHub app, and give it access to one or more of your repositories. Once the app has been installed, you will be redirected back to Count and prompted to choose: - Repository - the GitHub repository containing your dbt project - Branch - the default branch to use - Schema - the name of the database schema that contains your dbt models (this is usually defined in the appropriate profiles.yml file) - dbt version - the version of dbt to parse your project with Once these details are confirmed, Count will then check your repository and attempt to determine: - Project name - the name of your dbt project - Project file location - where in your repository the dbt_project.yml file is located - Default model path - the default location for new model files You may also define: - Environment variables (optional) - any environment variables required by dbt to parse your project files. Once set, non-secret variables are accessible from Jinja using the env_var() macro. ### Selecting dbt metadata in the canvas With the dbt Core integration, is possible to access different versions of your dbt metadata in different canvases. In the table pane, a metadata selector button will appear which allows selecting: - GitHub branches (if the GitHub app is installed) - Uploaded files (if any manifest files have been uploaded) Clicking the status indicator shows additional information about your dbt metadata, including: - Which commit it was generated for (if applicable) - Some information on the contents of the dbt manifest If a branch is selected that has never had any metadata generated, then a warning will appear. To generate metadata for this branch, click the Refresh now button. ### Editing models in Count Any cell can be annotated as a dbt model using the toggle in the cell controls. If enabled, a dbt icon will also appear in the corner of the cell. Once a cell has been marked as a model, any changes to its contents will be included in commits to GitHub. To signify the deletion of a model, just remove the contents of the cell with the model toggle enabled. Model cells behave in all other respects like other cells - they can be referred to by their names or by the ref() macro, and renamed or deleted. Once changes are ready to commit, clicking the Commit to GitHub button will open the model diff viewer. Here it is possible to: - Choose the branch to commit to - Choose a commit message - Choose the files to update - (Optionally) open a pull request after committing When generating diffs, Count compares cell names to model names. If no model with that name exists, the cell is understood as a new model, otherwise as a change to an existing model. When adding a new model the directory defaults to the one set in the connection dbt settings. To choose a different directory and/or file name, click the folder icon: One step to be aware of when viewing diffs is the process of model compilation. Here Count will analyse the dependency graph of your cells, and ensure that any diffs it generates are compatible with dbt. Consider the following case that involves a mix of model and non-model cells: The changes made in this example when compiling models include: - my_new_model refers to cell upstream_cell, so upstream_cell is included in my_new_model as a CTE. - my_new_model_2 refers to model upstream_model by name. To be compatible with dbt, this reference is converted to a ref(). Other changes may include: - Replacing any jinja expression involving the Count-only cells variable with the compiled output of that expression. - Hoisting and deduplicating any shared macro or set expressions. The changes made here are the same as those made when exporting SQL and selecting the SQL + Jinja option. When Count has made changes to your model definition, those changes will be listed above the diff: ### What actions does the Count GitHub app perform? Once the GitHub app has been installed on a repository, it is used for a number of tasks: - When refreshing your dbt metadata, the app is used to retrieve a private URL to download your repository as a .zip file. This URL is then sent to a temporary isolated virtual machine (VM), which downloads the zip file, unpacks the contents into a temporary directory, and executes dbt parse. The generated artifact files (like manifest.json) are then extracted from the VM, and the VM is deleted. - When committing to GitHub, the app is used to generate commits and open pull requests in your repository. - (Optionally) if you choose to change your commit authorship to your GitHub account, the app is used to verify your identity and view your GitHub email address. The permissions required by the app are therefore: - Read access to repository contents - for task 1 - Write access to repository contents - for task 2 - Read and write access to pull requests - for task 2 - Read access to your personal email addresses - for task 3 #### dbt Cloud integration URL: https://learn.count.co/data-sources/database-connection-overview/dbt-integration/dbt-cloud-integration Import your dbt Cloud models into Count ## Create and configure a dbt Cloud integration Follow this simple step-by-step guide to set up your dbt Cloud connection. ## Step-by-step guide In an existing database connection, select Manage connection, then select the dbt tab. To connect you will need: - An Access URL for your dbt Cloud account - An API token for a user/service account with the following permissions - Read-only - Metadata only - An account that conforms to the dbt Cloud metadata API prerequisites Once your credentials have been verified, you will first need to select a dbt Cloud account to use, after which your dbt Cloud jobs will be listed. For each job, Count can extract dbt metadata by reading the manifest.json and/or run_results.json files for a particular step in that job. These files are referred to by dbt as Artifacts, and contain information about your models and tests. You should select artifacts for each job depending on the information you would like to view in Count: - If the step involves dbt build or dbt compile (for example) then Count will have access to raw and compiled SQL if you select manifest.json. - If the step involves dbt build or dbt test (for example) then Count will have access to test results if you select run_results.json. In most cases, it will probably suffice to find the single step that performs dbt build and select both the manifest and run results from that step. Once you have selected the appropriate artifacts, click Finish setup and Count will request these files from dbt Cloud. When the metadata has been retrieved successfully, a message will be displayed at the bottom of the page: ## Troubleshoot Error creating dbt Cloud integration: Invalid token You may see this error if your API token is incorrect. Check that the token is valid for the Access URL you have provided. Error creating dbt Cloud integration: getaddrinfo ENOTFOUND You may see this error if your Access URL is incorrect. Check that the Access URL is valid using the instructions above. ## MCP connections URL: https://learn.count.co/data-sources/mcp-connections Bring in data and context from any tool in your business. ## Introduction Much like database connections, Count can also connect to any remote MCP server via MCP connections. MCP connections act similarly to database connections - they receive queries and return results. The main differences are: - MCP connections don't have to return tables, they can return any kind of textual result - JSON, markdown, plain text etc. - MCP cells can only be created and edited by an agent. - MCP queries don't have to be read-only - you can use any MCP tool. ### Creating an MCP connection Click the Create new connection button from the workspace home page to see a list of pre-configured MCP connections: If your connection doesn't show up, please tell us using the in-app chat! In this case, it's always possible to use the generic MCP Server option at the end of the list. Selecting a pre-configured or default option will present the same connection options either way: - Name / Description - how this connection appears in Count - Authentication method - how the connection should be authenticated, either OAuth or Authorization header. - URL - the unique URL for the MCP server. This will be populated for pre-configured options, otherwise please consult the documentation for the service you wish to connect. The available authentication options depend on the chosen authentication method: OAuth OAuth is the most common approach to authenticating with MCP servers. You will be redirected to the MCP server and prompted to sign in to your account there. Upon granting access to Count, you will be redirected back with an access code tied to your MCP account. - Automatic client registration - many MCP servers are able to create an OAuth client on-demand, in which case you do not need to specify any OAuth client details if this option is supported by your MCP server. - Client ID / client secret - if your MCP server does not support automatic client registration, you will need to create a client first - please consult the documentation for the MCP server. Once you have created a client, enter the details here. - Scopes - some MCP servers support explicit scopes, which define the access granted to Count when sending requests to the server. If available, please ensure that all required scopes are selected. Consult the documentation for the MCP server if you are not sure. Note: Required scopes Some MCP servers require the offline_access scope to be granted before they will allow Count to connect. If you encounter issues when connecting and this option is available, try ensuring that it is selected. Note: OAuth clients are shared Once you have created an MCP connection using OAuth authentication, those credentials will be shared amongst all Count users with access to that connection. If the OAuth client is tied to your MCP server account, ensure that the connection is only shared with workspace members that should be able to use the MCP connection with your credentials. Authorization header Some MCP servers do not support OAuth, and instead require that a secret is passed in the Authorization header when making requests to the server, often in the form Bearer . If so, please enter the appropriate value for the header here. ### Configuring an MCP connection Most of the settings for MCP connections are shared with database connections, with the exception of tool settings. MCP servers expose a list of tools - these are the actions that the MCP server can perform. Most tools are read-only - for example, 'fetch my recent conversations'. However other tools are not, for example 'create a new issue for this bug report'. By default Count disables all tools that are reported to have side-effects by the MCP server. This does rely on the server providing an accurate overview of the tool capabilities, so please check that the appropriate tools are enabled after first connecting to an MCP server. The list of tools is refreshed automatically every day, but if you notice a tool no longer working as expected, try clicking the Refresh tools button to fetch the latest tool definitions from the server. Clicking a tool will show more information about the tool - this information is typically designed for AI agents to consume, but it is often helpful to read the descriptions of tools and their parameters to understand what their effects might be. ### Using an MCP connection Once connected, you'll first need to add the MCP connection to a project as usual, after which it will appear in the Sources list in the canvas. When an MCP connection is selected, the Tables pane shows available tools instead, indicating which are enabled or disabled. Once a tool has been used once, if it returns tabular data the result columns will also be shown here: To use a tool, simply ask the agent - the agent will look up the tools it has access to (excluding disabled ones), figure out how to use it, and respond with the results: Attempts to use a disabled tool will fail: ### MCP cells Some MCP tools can return a lot of information, which may overwhelm the context window of the agent. Count detects large responses and instead instructs the agent to create an MCP cell - this is a cell that represents the tool invocation. Agents can read and execute these cells just like other cells, and the results are cached in the same way. In this way, the agent can query and inspect the MCP tool results just like it does for other cells - running introspective queries, joining to other cells, constructing SQL or Python cells to analyse the results in more detail etc. Tabular vs. non-tabular results MCP tool results are returned to Count in various forms - often JSON, but also YAML, TOON, Markdown, or plain text. Most results are tabular in nature, and in these cases the MCP cell will show a table output. To see the raw response from the MCP server, select the Raw option from the output selector above the cell: If the MCP cell returns markdown-formatted text, it is possible to view the raw response as formatted rich text by selecting the Markdown format option under Table style in the design bar. ### Non-read-only tools If a tool has side-effects - i.e. it is not read-only - then it behaves differently in Count: - MCP cells can only call read-only tools - because cells run automatically most of the time, they are limited to calling tools that have no side-effects. - The agent requires confirmation when calling these tools - it will often ask for verbal permission, and it will always present a permission request prompt before executing these tools, whether invoked from Count, Slack, or an app using the Count MCP server. ## Upload files & CSVs URL: https://learn.count.co/data-sources/upload-csv-files Upload any CSV file into your canvases. You can upload a csv into a canvas in 2 ways. ## Option 1: via the data bar In the data bar on the left-hand side of the page, you'll see the option to Upload a CSV file. Click this button to open a file browser and select a CSV file to upload. You can also upload multiple CSV files by dragging them onto the canvas from your file explorer. ## Option 2: drag a csv file in You can drag a csv file directly into the canvas from your desktop. ## Querying a CSV file When a CSV file is uploaded a CSV cell is created in the local DuckDB database, which contains all of the rows from the file. To query this file just refer to it in a SQL statement by name, like any other cell. You can make changes to how Count reads a CSV file using the righthand canvas menu. This allows you to override the encoding options Count has detected and set your own delimiting, quote and escape characters as well as ignore / include a header row. ### Who can see uploaded CSV files? Any other viewers of your canvas will see the CSV cells you've created. If you wish to keep your CSV files private, you should use a private project, or make sure you are the only person permitted to view the canvas. ## Google Sheets URL: https://learn.count.co/data-sources/google-sheets Connect Google Sheets to Count. Our Google Sheets connection allows you to bring in live data from your Google Sheets, which can then be used and combined with other data sources in a canvas. [Video: Get started with GoogleSheets] ## How to set up your Google Sheets connection There are two options for connecting your Google Sheets to Count: - OAuth authentication: This is the easiest way to connect but may not be suitable for large workspaces with many users. It gives Count access to any Google Sheets that you have access to. - Credentials file (JSON format): This method is more secure for larger workspaces as it restricts access to only the Google Sheets that a service account has access to. ### OAuth authentication (1) Select the OAuth Authentication method, click Authorize, and go through the authentication flow. (2) Click Connect to finalise your setup ### Credentials file (JSON format) You can use either your personal account or a service account for this. If you use a service account, it will need to have both the Google Sheets and Google Drive APIs enabled. To get the credentials file, you'll need to have completed the following steps. A full step-by-step guide can be found below. - Sheets API & Drive API Enabled - Service Account Created - JSON Key downloaded - Sheet shared with the Service Account email address How to get your credentials file - a step by step guide You can follow the steps outlined here, or go directly to Google's help site for more information. This is a 3-step process. ### Step 1: Google Cloud Setup - Go to the Google Cloud Console. - Select the appropriate project or create a new one. - Enable APIs: - In the search bar at the top, type Google Sheets API. Click it and select Enable. - Crucial Step: Go back to the search bar, type Google Drive API, and Enable that as well. (This is often required by libraries to find/open the files). ### Step 2: Create Service Account & Keys - Navigate to IAM: - In the sidebar menu (≡), go to IAM & Admin > Service Accounts. - Create Account: - Click + CREATE SERVICE ACCOUNT (top center). - Name: Give it a name (e.g., sheet-updater). - ID: It will auto-generate an email address (e.g., sheet-updater@your-project.iam.gserviceaccount.com). Copy this email address now—you will need it in Step 3. - Click Create and Continue. - Grant Permissions : - Under "Select a role", choose Basic > Viewer. - Click Continue, then Done. - Generate Key (The JSON File): - You should now see your service account in the list. Click on the Email address link to open its details. - Go to the Keys tab (top bar). - Click Add Key > Create new key. - Select JSON and click Create. - A file (ending in .json) will automatically download. Rename this file to credentials.json and move it to your project folder. ### Step 3: Share the Sheet The service account is a "user" with its own email address, but it cannot see your files until you invite it. - Open the specific Google Sheet you want to access. - Click the big green Share button (top right). - In the "Add people" box, paste the Service Account email you copied earlier (the one ending in ...iam.gserviceaccount.com). - Ensure the permission is set to Viewer or above. - Uncheck "Notify people" (since it's a robot, it doesn't read email) and click Share. Then in Count, select your credential file and click Connect. ## Data access By default, you can query any Google Sheet in your drive (limited by the supplied credentials if that connection method has been used). The connection is live, so whenever changes are made in your Google Sheets, they will be reflected in Count. You'll need to refresh the connection if you add, rename, or delete files or tabs/sheets. ## Web search URL: https://learn.count.co/data-sources/web-search Allow Count's agent to search, read and bring in data from the web. When you're deep in a piece of analysis, it's often useful to pull in information from the web. It can add context, enrich what you're already looking at, or surface data that isn't in your warehouse. That information might be quantitative (for example, published market-size figures or the latest exchange rates) or qualitative (a competitor's announcement, or the docs for a tool you're evaluating). The Count agent can reach the web through three tools, each designed for a different job. All three bring their results directly into the canvas, where the agent can work with them like any other cell. ## Web search Web search lets the agent search the web and bring the results back into the canvas, using them as context for the rest of its analysis. The agent decides what to search for based on what you've asked it to do, and it can run multiple searches to gather what it needs. Count uses Brave Search's API for this. Brave operates with zero data retention, so none of your search queries or results are stored by Brave. ## Web fetch Where web search finds pages, web fetch reads them. Give the agent a URL, or let it use one it found through web search, and it can retrieve the full content of that page, read it, and pull back whatever information is relevant. Web fetch is powered by Cloudflare. ## Download CSV The agent can download a CSV file from any public internet URL and place it directly into your canvas as a CSV cell, ready to query with SQL like any other data. This is handy for pulling in open datasets or exports that live at a fixed link. Once it's in the canvas it behaves exactly like an uploaded file. See the Upload files & CSVs page for how CSV cells work. ## Controlling web access Access to the web is managed in your workspace settings. From there, a workspace admin can turn off the agent's access to any of these three tools individually, giving you full control over whether, and how, the agent reaches the internet. Note: Web tools are separate from Python These three web tools are governed independently from Python cell network access. Python cells can also reach external APIs and URLs, but that ability, and which domains are permitted, is controlled by its own Python settings on the same settings page. If you're using Python to call out to the web, see the Python cells page for the details. To understand more about how the underlying Brave and Cloudflare integrations handle your data, see the Count Trust Center. ## Import from other tools URL: https://learn.count.co/data-sources/import-from-other-tools Count can import from a range of other tools allowing you to quickly consolidate your workflow. The canvas is a flexible space to work, and supports importing content from many popular whiteboarding and data analytics tools, including: - Miro - SQL files ### Import Miro files URL: https://learn.count.co/data-sources/import-from-other-tools/import-miro-files Quickly bring in existing Miro boards into your Count canvas. ### 1. Copy objects from Miro Copy the objects from Miro onto your keyboard either by right-clicking or using a keyboard shortcut. ### 2. Paste into a Count canvas Then simply paste those objects into a Count canvas. Everything will be imported as the same object type (e.g. a Miro sticky note will be a Count sticky note). If your board contains objects that Count does not yet support, those objects will not be imported. ### Import SQL files URL: https://learn.count.co/data-sources/import-from-other-tools/import-sql-files Go from nasty, nested SQL to a clean, clear DAG. Use these step-by-step instructions to see how to use an existing SQL statement in Count, and visualize it as a connected DAG of cells. ### 1. Copy the query into your clipboard Copy directly from your favorite IDE. Count can only handle SELECT and WITH statements. If you try to run any CREATE, UPDATE, or DELETE statements, they will not be executed. ### 2. Paste into a new, blank cell Paste the query into a new cell. This query will run as expected, but it's strongly suggested to turn that 1 query into a DAG of connected cells. ### 3. Click to explode CTEs to cells Clicking the explosion button will automatically take your CTEs and represent them as connected cells. This makes it easier to understand your query, debug, and communicate with others. --- # Working in The Canvas Learn more about how working in and with the Count canvas, from the agent and canvas objects to team collaboration and shareable reports. ## AI Agent Overview URL: https://learn.count.co/working-in-the-canvas/ai-agent Spend less time remembering that date function or tweaking that visual. [Video: Getting Started GIF: Ask the agent] Count AI isn't a chatbot bolted onto your data. It's an agent that investigates a question the way an analyst would, on a platform governed, transparent and auditable enough to let that happen at scale, working alongside your team rather than in a private chat window. Ask it a question in plain English and it gets to work in your canvas: writing queries, checking its results, and building the charts and tables you need. You don't need to know SQL, and you don't need to know where the data lives. Every query it runs and cell it creates is a normal, editable object in the canvas, so you can open it up, see how it reached an answer, and fix it if something's off. ## The wider harness Count AI works by drawing on every part of Count: - Data sources: it can query your warehouse, uploaded files, and any connected business apps or the web, quantitative and qualitative alike, so an answer can be checked against more than one kind of source rather than resting on a single query. Data sources - Context: it reads the skills and context you've set at the workspace, source or project level, plus your Count Metrics semantic layer, so it's working from your business logic rather than guessing at it. Build trusted context. - Analytics engine: its queries run on Count's own compute layer, so it can dig as deep as it needs without adding to your warehouse bill. - Integrations: reachable from Slack, the API, or agentic tools like Claude and Cursor, so a question gets the same answer wherever it's asked. Integrating Count. - Presentation: its output can become a live report or a shared canvas, not just an answer in a chat window. Reports and alerts. - Governance: auditing works two ways. Telemetry gives admins a workspace-wide view of what agents are doing, and canvas lineage lets anyone trace a specific piece of analysis themselves. ## Who's it for Analysts use it to skip the repetitive work and get to the interesting part faster. It drafts the query you were about to write, gives you a first pass at the answer, and leaves you time for the work that actually needs a person. Everyone else (product, growth, finance, ops) uses it to ask a question in plain language and get an answer built on the same governed data your analysts use. That means it's something an analyst can check, rather than something they have to redo. ## What to ask it The value of the agent is found in asking it to dig into real business questions and challenges: - When something's off: "Margins are down but sales are up, why?" Hand it a vague worry and it breaks the problem into testable pieces, rather than asking you to be more specific before it'll help. - When you've inherited someone else's SQL: paste it in and ask for a walkthrough. It splits it into steps, explains what each one's doing, and points out the bit that looks wrong. - When you don't know where to start: "Help us understand churn risk" is a perfectly good prompt on its own. It decides what's worth investigating and shows its thinking as it goes. - When one question isn't enough: it can spin up sub-agents to chase several threads at once, then bring the findings back together, so you don't need to break the problem down yourself. ## Enabling Count AI Count AI is disabled by default for workspaces created before November 17, 2025. To enable Count AI: - Go to workspace settings (you'll need Owner permissions) - Navigate to the "AI" tab - Toggle the "Enable AI" setting on Once enabled, any analyst in a canvas can use the AI agent. Owners can disable it at any time, which immediately removes access for all workspace members, though any content produced by AI agents will persist. ## How Count's AI agent works Count AI creates and edits cells in your canvas. These may reference: - Catalogs - Databases - Data connections via MCP - Other cells - CSV files uploaded to the canvas - Information from the web Important: The agent does not execute queries directly against your database unless the user gives explicit approval. ## Privacy and security - GDPR compliant - Count AI meets European data protection standards - No model training - Neither Count nor our partners (OpenAI, Google, Anthropic) train models on your data - SOC 2 accredited - Built on Count's secure platform - Controlled access - Count AI can only access metadata (column names, types, descriptions) from databases without your pa and row-level data from cells in the canvas Learn more in our Terms of Use and Security pages. ## Important notes on accuracy Count AI uses artificial intelligence that may produce inaccurate or misleading outputs. Always verify results before making decisions or taking action. AI outputs are not facts and shouldn't replace expert judgment. ### Count's AI Agent usage guide URL: https://learn.count.co/working-in-the-canvas/ai-agent/ai-agent-guide Get started with Count AI Agents This guide walks through how to add AI agents to your canvas, provide them with the right context, and get the most value out of them. Count’s agent operates like an AI analyst inside your canvas, using the exact same tools that human analysts use. ## Getting started ### Adding an agent to your canvas - Open any canvas where you want to analyze data. - Click the ✨ Sparkle icon in the left sidebar to open the Agents panel. - Start asking your question. Use the microphone button to speak your question instead of typing—this is a great way to quickly share detailed context! NB: If you don't have the AI Agent option in your workspace, an Owner of your workspace will have to enable this in the Workspace Settings. ### Managing agents When an agent is active, it lives in the left-side panel. - Switching Agents: Click History in the top-right to switch between all agents in the canvas (including those created by other users). - New Agent: Click the plus (+) icon to create and select a new agent. There is no limit to the number of agents that can be in, or active in, a canvas. You can run multiple agents concurrently to investigate different things at once. Note: Resource limits Running multiple agents simultaneously will accelerate your workspace credit usage. Agents will run for a maximum of 1 hour before timing out automatically. They will continue working toward their end state even if deselected, if no one is in the canvas, or if the browser tab is closed. ## Providing data and context For the agent to give you the best answers, it needs to know what data to look at and the business logic behind it. ### How agents access data The agent has access to all data sources within the canvas and can autonomously locate relevant data across your catalogs, databases, MCP data connections and search for open source data and context on the Web. 🛡️ Safety First: The agent will never execute a query against your database without your direct approval. When working with a catalog, the agent automatically reads the full contents of *.dataset.yml files, *.view.yml files, and all AGENTS.md files. This includes structured fields (measures, dimensions, joins) as well as any written comments and documentation inside those files. ### Adding specific context You can manually supply the agent with specific canvas content (like a cell, sticky note, or CSV) so it understands exactly what to reference. You can do this by: - Using @ mentions: Type @ and select catalog, database connection, or cell names. - Selecting objects: Simply select non-data objects like text boxes and sticky notes and ask a question. This is perfect for sharing definitions, terminology, or a list of priority questions directly in the canvas. ### Establishing persistent context You can provide agent-specific context at different levels so you don't have to repeat yourself in every prompt. Learn more in our build trusted context section. - Workspace-level: Applies across your entire workspace. - Connection-level: Applies to a specific connection. - Catalog-level: Applies to a specific semantic layer catalog. - Project-level: Applies within a specific project. Context can also be maintained via our Public API, which allows you to manage your definitions externally. ## Querying the agent: tips for success The more specific your prompt and the better your context, the better Count AI can answer your question. - Be specific: Instead of asking "Show me sales data," try "Show me monthly sales broken down by region for 2024." - Define custom metrics: If your metrics aren't in a catalog, define them. (e.g., "Show me how margin (Profit / Sales) varies by customer," or "Calculate monthly retention as users active in month N who were also active in month N-1.") - Ask follow-up questions: If the first answer isn't quite right, just tell the agent what to adjust! It maintains conversational context just like chatting with a colleague. ## Understanding and inspecting output Agents create their output within a standard frame on your canvas. ### Viewing progress Find and select an agent in the Agents panel to see its progress. - Atomic steps: The panel outlines the distinct steps the agent is taking (e.g., canvas actions or "thinking"). Click the disclosure arrow (>) to expand and understand these steps. - Errors are normal: It is completely normal to see red error steps. Like any human analyst, the agent may occasionally make syntax errors in SQL or run into analytical walls. It uses these errors to iterate, adjust, and try again. Note: Note on permissions Users with Data Editor permissions can see and continue any conversation in the canvas. Users without these permissions can view the conversations, but cannot continue them or start new ones. ### Types of output The agent can create several types of canvas objects, all of which are fully editable by you: - Low-code cells: Whenever possible, the agent builds visual cells that clearly show where data came from—no SQL required. - SQL cells: For complex questions, the agent writes raw SQL. You can click "Show input" on any cell to see the exact query it generated. - Visualizations: The agent automatically generates charts, tables and maps based on what makes the most sense for your specific question. - Text and sections: The agent organises analysis into sections and adds text boxes to add narration, including insights, sources used and caveats to be aware of. ## Troubleshooting Count AI works best with analytical questions regarding data you've actively provided as context. It may struggle with questions about data it doesn't have access to, or very ambiguous queries without sufficient background context. If you aren't getting useful results, try: - Adding more specific context using @ mentions. - Breaking complex, multi-part questions down into smaller, step-by-step requests. - Explicitly defining custom terms or metrics in a sticky note and selecting it as context. ### Count AI FAQs URL: https://learn.count.co/working-in-the-canvas/ai-agent/ai-agent-faqs Find answers to the most common AI questions we see ## Access and permissions Who can use Count AI? Currently, any Analyst, Owner, or Admin with data editing permissions in a canvas can use Count AI. Who can enable/disable Count AI? Only workspace owners can enable or disable Count AI in workspace settings. What happens when Count AI is disabled? Disabling Count AI immediately removes access for all workspace members. Any cells and visualizations previously created by agents remain in your canvases. ## Pricing and usage How does this work with pricing? The AI agent is included in all paid plans with daily fair usage credits per user. What if I run out of credits? You can buy more credits for power users, or wait until they reset. The AI agent can only do things a normal analyst could anyway, so you won't lose access to any functionality within the platform—just the ability to use the agent to speed you up! ## Data and queries Will Count AI query my database directly? It can do, but it will ask the user for permission to do so first. Count AI works automatically against cached catalogs, cached database cells, DuckDB cells, and CSVs. If it needs to query your database directly it will show the prompt before it does so. What data can Count AI access? Count AI can access metadata (column names and data types) plus row-level data from any source you explicitly add when creating an agent. ## Privacy and security Is Count AI GDPR compliant? Yes, Count AI is fully GDPR compliant. What are the security implications? Our AI agent is part of the same security governance we currently offer, in line with SOC2 standards and GDPR compliant. Count AI is built on Count's SOC 2 accredited platform. Does Count or its AI partners train models on my data? No. Neither Count nor our model partners (OpenAI, Google, Anthropic) use customer data for model training. Can I control who uses AI features? Yes. Workspace owners can disable Count AI at any time from workspace settings. ## Accuracy and reliability How accurate is Count AI? Count AI is powered by artificial intelligence algorithms whose accuracy varies. Outputs may include inaccuracies or be misleading. Should I trust Count AI outputs without verification? Always verify information from Count AI before making decisions. Treat AI outputs as starting points that require validation, not as facts or substitutes for expert judgment. What should I do if Count AI gives an incorrect answer? - Verify the data sources the agent is using - Check the SQL or logic in any cells it created (click "Show input") - Provide more specific context or rephrase your question - For complex analysis, use Count AI to draft initial work that you then validate and refine ### Slack URL: https://learn.count.co/working-in-the-canvas/ai-agent/ai-agent-slack Using Count's AI Agent from Slack Kick-off some analysis using Count's AI agent without leaving Slack. Start a new thread for a new question, or have the agent weigh in on a discussion in an existing thread. The agent will respond in the same thread, and you can ask follow up questions to dive deeper. Note: Slack notifications You can also use the Slack integration to receive notifications and alerts. See here for details about this. ## Install the Count app for Slack Before you can interact with Count's AI agent from Slack will first need to install the Count app for Slack. Install the app by visiting your user account settings (accessed by clicking on your avatar icon in the Count workspace > Account) and clicking the Connect Slack button. Once installed, see the instructions below to start talking with the AI agent. Read about how Count uses your data in our Privacy Policy. ## Interacting with the agent from Slack You can start a new agent (in a fresh canvas) in the following ways: - Mention the Slack app in a channel (e.g. "@Count can you help me understand why our sales dropped last month?") - Mention the Slack app in an existing thread (e.g. "@Count do you have any insights on this?") - DM the slack app directly (e.g. "Hey Count, can you help me understand our customer churn?") If you haven't used the Slack app in a channel before, you likely need to do two things first: - Invite the Slack app to the channel (Slack should prompt you to do this when you mention the app) - Select a project for the new canvas (the app will prompt you to do this) When a new agent is started, a link to the canvas will be shared in the thread and when it's finished it will post its response, some suggested next steps, and a screenshot of what it's created or changed in the canvas. For existing agent threads in Slack, you ask follow up questions by: - Mentioning the Slack app in the thread (or just replying in the thread for DMs) - Clicking one of the next steps buttons in the agent's response ## Project / channel mappings When you ask a question and select a project, you'll be asked if you want to always use that project when you ask questions in that channel. This is called the project/channel mapping. You can manage this using the following slash commands: - /count set-project opens a modal to select a project - /count unset-project removes the project/channel mapping for the channel - /count project shows the current project/channel mapping for the channel ## Sync between Slack and the canvas in Count The conversation with the agent is synced between Slack and the canvas in Count so you can see the full conversation history in either place. The only difference is that we don't send all of the agent's output to Slack as it would be too noisy. This is true for both the initial response and responses to any follow up questions. You can also ask interact with the agent from either UI. Ask follow up questions or approve/reject agent database requests from Slack or the canvas. ## Permissions Your Slack user is linked to your Count user and any actions like starting or interacting with an agent will be done on behalf of your Count user. The same permissions apply as if you were using Count directly. The main difference is that other users in the Slack channel who don't have access to the project/canvas, while they won't be able to interact with or start agents, they will still be able to see the agent's responses in the channel. This is important to keep in mind when sharing insights from the agent in Slack channels. ## Navigating the canvas URL: https://learn.count.co/working-in-the-canvas/navigating-the-canvas How to get around the canvas The canvas is where you bring your data, analysis, visuals and discussion together. Here’s a guide to the key areas and navigation features. ## Toolbar Located at the bottom of the screen, the toolbar contains all of the options for inserting content into the canvas. ## Data sidebar On the left-hand side of the screen, the data sidebar shows all of the schemas and tables in your databases and catalogs, as well as the cells in your canvas. Anything in the data bar is a valid query target. ## Design sidebar On the right-hand side of the screen, the design sidebar shows the controls for modifying the canvas or any selected objects. Controls here may be disabled or hidden depending on your canvas role. If no objects are selected, canvas design options and data options are displayed instead. ## Help menu The help menu located in the lower right contains links to documentation, release notes and our in-app chat support. ## Navigation ### Zoom in/out - Trackpad – two-finger pinch gesture - Mouse – hold Ctrl / Cmd and scroll - Keyboard – press the + / - keys (see all keyboard shortcuts here) ### Pan - Trackpad – two-finger scroll in any direction - Mouse – hold the space key and drag in any direction. Or scroll to pan up/down, or scroll while holding the Shift key to pan left/right. - Hand tool – press the H key to switch to the Hand tool, then drag to pan. ### Undo/redo The canvas contains an undo stack that allows you to undo or redo changes you've made: - Undo – Ctrl / Cmd + Z - Redo – Ctrl / Cmd + Shift + Z ## Updating your navigation preferences You can also update your canvas preference to optimise your experience in the canvas given your computer set up (Mac vs Windows, trackpad vs mouse). Available preferences are: - Scroll to zoom - Right-click and drag to pan Access these settings from the Count logo menu at the top right-hand corner of the screen and select Preferences. ### Canvas toolbar URL: https://learn.count.co/working-in-the-canvas/navigating-the-canvas/canvas-tool-bar No one likes a blank page. ## Adding content The toolbar sits at the bottom of the canvas and contains all the controls for adding and interacting with content. - Controls with an arrow ▾ open a menu with additional options. - Some buttons may not be visible depending on your canvas permissions. ## Count AI Use AI to generate queries, explanations, or visualizations. ## Cursors - Move (M) – Select objects by clicking on them, or drag to create a selection box. - Hand (H) – Pan the canvas by dragging. You can also hold the spacebar to temporarily switch to this tool. - Scale (K) – Resize objects while keeping their contents in proportion (useful for text boxes, charts and frames). ## Cells - SQL cell (/) - Inserts a cell for executing SQL queries. - Python cell (Y) - Inserts a cell for executing Python queries. Find out more about how to query data using these cells. ## Low-code cells - Visual (V) – Create a visual cell and open the visual editor. - Table (X) – Create a table cell and open the visual editor. Find out more about low-code cells, and how to visualize data. ## Controls Interactive inputs you can add to the canvas: - Date picker – Select a date from a calendar. - Multiple select – Choose multiple values from a column. - Single select – Choose a single value from a column. - Number input – Enter a number manually. - String input – Enter free-text. - Slider – Pick a value by sliding. - Toggle – Switch between on/off. - Table filter – Add filters to a table. Find out more about using Control Cells. ## Annotation - Sticky (S) – Add a sticky note for comments or reminders. - Text (T) – Add a markdown-enabled text box. Find out more about formatting text and using markdown shortcuts. ## Shapes & media - Rectangle (R) – Draw a rectangle. - Ellipse (O) – Draw an ellipse. - Line (L) – Draw a straight line. - Connector (Shift + L) – Draw a smart connector line, with optional snapping to objects. - Pencil (P) – Freehand drawing tool. - Stamp (U) – Insert an emoji stamp (optionally attach it to another object). - Upload image – Upload an image (gif, jpeg, png, svg, webp; max 10MB). You can also drag images directly onto the canvas. - Embed link – Embed third-party content into the canvas. ## Frame - Frame (F) – Create a frame to contain and organize multiple objects. Frames can be resized and moved as one. ## Comment - Comment (C) – Add a comment and open the comments sidebar. You can attach comments directly to objects. ### Data sidebar URL: https://learn.count.co/working-in-the-canvas/navigating-the-canvas/data-sidebar Not to be confused with the data pub The data sidebar gives you quick access to your catalogs, databases, schemas, tables, fields, and the cells in your canvas. - You can resize the data sidebar by dragging the right-hand edge, or adjust the divider between the Tables and Cells panes. - You can hide or show the sidebar using the arrow button at the top, or the shortcut Cmd + \ (Mac) / Ctrl + \(Windows). ## Tabs - Data – Displays your available data sources, tables, and cells. - Overview – Shows a summary of the sources and objects used in your canvas. ## Sources The Sources pane lists all catalogs and database connections available in your canvas. - Active source – Selecting a source makes it active. Any new cells created from the toolbar default to this active source. - Colors – Each source has a color used to visually distinguish its cells in the canvas. - Click a color to edit it. - Default source colors can also be set in the database connection settings. ## Tables The Tables pane lists the available tables for the active source. - For database sources, tables are grouped by schema. - Expand/collapse schemas and tables to browse their fields. - Use the plus button next to any schema, table, or column to insert a summary of that object directly into the canvas. - Use the search bar to quickly find a table or field. - Use the filter icon to limit the list by schema or table, then search within that scope. - Refresh – Click the status icon at the top of the Tables pane to refresh the list of tables for the active source. ## Schema display - Click on a table to expand its schema and see all fields. - Data types are shown next to each field (e.g. STRING, DATE, JSON). Analysts can toggle type display off in Preferences if preferred. - Partitioning columns are shown in the sidebar when available. - Expand array/struct fields to see their nested schema directly in the sidebar (BigQuery only). ## Cells The Cells pane shows the list of cells for the active data source. - Use the search bar to find a specific cell. - Click the navigation icon next to a cell to jump to it on the canvas. - Use the plus button next to a column to insert a summary of that column into the canvas. ### Overviews URL: https://learn.count.co/working-in-the-canvas/navigating-the-canvas/overviews Make canvases easier for visitors to understand and get started with. An overview is a rich-text area in the left-hand sidebar. It’s designed for information that should be visible wherever you are on the canvas, like a guide, summary, or checklist. ## Why use an Overview? Overviews are helpful for: - Explaining the purpose of a canvas or framing your analysis. - Adding introductions, instructions, or notes for collaborators. - Adding contact details of the canvas creator. - Creating a shared to-do list for development. - Centralising control cells so filters are always accessible. ## Using overviews ### Adding content - Start typing paragraph text directly. - Type / to add rich-text components such as headings, blockquotes or code blocks. You can also select a control cell on the canvas to make it usable in the Overview. - Use Markdown syntax (the same as text cells) for formatting. - Type @ to: - Mention a user (users will receive an email notification, unless they’ve disabled notifications in their user settings). - Link to a frame or cell (clicking zooms the viewport to it). - Frame links adopt the stroke colour of the frame, which can help with navigation when there are many sections. ### Managing content - Reorder items → Use the drag handle on the left of each element to move it up or down. - Delete items → Place your cursor at the end of the item and press Backspace. This removes that component from the Overview. ### Quick-start options If the Overview is empty, you’ll see shortcuts to add: - Filters → Adds copies of all canvas control cells to the overview. Note, these will cease to function if the control cells are deleted from the canvas. - Canvas guide (AI beta) → An AI-generated summary of your canvas with suggested frame/cell explanations. - Table of contents → A nested, clickable list of frames and cells for fast navigation. - To-do list → A ready-to-use checklist template. ### Overview example It's up to you what you would like to include in your Overview pane, however if you need, we've outlined some sections to get you started: - Canvas title -> The title of your canvas. - Overview -> A summary of the canvas. - Purpose -> What does your canvas do and achieve. - How to use -> Help to navigate your canvas. - Methodology and assumptions -> Any data nuances to be aware of. - Frames -> Link your frames using '@' for fast access. - Control cells -> Add your control cells in using '/'. - Canvas log -> Log your name, job title and date of creation to start an audit trial for accountability and so users know who to ask questions to. ### Controlling visibility At the bottom of the Overview you’ll find two toggles: - Canvas visibility → When on, the Overview opens by default instead of the Data tab. - Presentation visibility → When on, the Overview appears in Presentation mode. You can also show or hide the Overview panel: - Panel toggle – Use the arrows icon at the top of the sidebar to show or hide the Overview panel while working in the canvas. - Presentation toggle – In Present view, use the Overview button in the toolbar to show the panel (and the X to hide it). ### Templates URL: https://learn.count.co/working-in-the-canvas/navigating-the-canvas/templates Speed up creating repetitive or standardised layouts by combining objects into reusable templates. Templates let you save time and ensure consistency by reusing logic, layouts, or designs across projects and workspaces. They’re especially useful for: - Starting new canvases with a consistent structure (dashboards, reports, frameworks) - Sharing reusable elements like control panels, KPIs, or analysis frameworks - Standardising styling and workflows across a team There are two types of templates: - Custom templates – templates you and your team create, either scoped to a project or the whole workspace. - Built-in templates – provided by Count, including: - Getting started guides - Example canvases (with data) - KPI/metric cards - Presentation layouts - Visualization examples ## Creating a template You can create a template from either an entire canvas or just a selection of objects. - From a whole canvas → click Save as template in the design sidebar (when no objects are selected) or from the File menu. - From a selection of objects → select the objects, then click Save as template in the design sidebar. In both cases you’ll see the Save as template dialog where you can configure: - Template name – the display title of the template - Description – optional notes for clarity - Project vs Workspace – share only in the current project, or make available to the whole workspace - Preview area – choose which part of the canvas is shown in thumbnails - Upload image – add a custom thumbnail These properties can also be updated later after the template has been created. When you save a template, a new “Template” canvas is created in the same project as your original canvas. It will appear in the project sidebar with a Template badge next to the name. ## Editing templates Templates are just canvases. Open a template and edit it like any other canvas: move objects, adjust logic, update visuals. Key differences: - Alerts cannot be added to templates. - Changes are unpublished by default – edits are saved continuously, but other canvases won’t see them until you click Update template. Updating a template publishes a new version. Old versions remain available in version history. ## Using templates There are two main ways to use templates: - Insert a template into an existing canvas - Click Add template in the corner of a canvas. - Browse your workspace’s custom templates or built-in Count templates. - Use template to insert it directly, or Preview first. - Create a new canvas from a template - Right-click a template on the project home page and select Create canvas from template. - Or, if pinned, pick it from the pinned shortcuts in your project. When you insert a template: - Shared styles are copied. - Cells with duplicate names are renamed. - Images and CSVs are copied. - Overviews are copied. - Database connections you don’t have access to will error. ### Canvas version control URL: https://learn.count.co/working-in-the-canvas/navigating-the-canvas/canvas-version-control Ensure your work is never lost. Every canvas can have multiple versions, which are snapshots at a point in time. Versions cannot be edited or deleted, so are very useful in understanding the history of the canvas. ### Creating a version Count will periodically automatically save versions of your canvas, but it is also possible to manually save a version - just head to the version history menu and click the plus icon. You are able to view the version history if you're an editor of this canvas. ### Viewing versions The version history pane displays all versions of the canvas, and highlights the one you are currently viewing. To view an old version, simply click any from this menu and you'll see the canvas as it was at a given point in time. Unless a Data snapshot is saved with a version, any current query results will not be saved. ## Viewing old versions Select an previously-saved version with a snapshot to see what the data and the canvas looked like at that time. ## Restoring old versions When restoring an old canvas version that contains a data snapshot, that snapshot will replace any current data snapshot for the canvas. ### Duplicating And Merging URL: https://learn.count.co/working-in-the-canvas/navigating-the-canvas/duplicating-and-merging Safely iterate on canvases using a familiar duplicate-and-merge workflow. ## Duplicating a canvas If you have permissions to both edit a canvas and create canvases in the same project, you can access the Duplicate canvas option from the canvas File menu (or by right-clicking a canvas from the project canvases list): When a canvas is duplicated: • All of the canvas contents are copied, including any uploaded CSV files • The caching and scheduling settings of the new canvas are inherited from the parent canvas • The new canvas will always be unlocked by default • The new canvas inherits any tags from the parent canvas ## Merging changes A canvas that was created by duplication is a "child" canvas of its "parent" (source) canvas. In this case, it is possible to atomically apply many changes at once by merging the child into the parent. Merging is helpful when you need to make changes to a widely-read canvas or report without interrupting the experience for viewers of that document - just duplicate it, make your changes in private, and merge the updates when they're ready. Any viewers will receive the merged changes applied in a single step, and can continue uninterrupted. Child canvases show a Merge changes button in the navigation bar: This option is available if: • You have an analyst role in the child canvas. • You also have an analyst role in the parent canvas. • The parent canvas has not been deleted. After confirming the merge: • The duplicated canvas will be moved to the trash. • A new version will be saved for the parent canvas. • The contents of the parent canvas will be replaced by the contents of the child canvas - for example, objects that don't exist in the child canvas will be deleted. • Anyone else viewing the parent canvas will see the updates immediately, whether it is locked or unlocked. To be sure that concurrent edits cannot occur during a merge operation, ensure that the parent canvas is first locked. ### Keyboard Shortcuts URL: https://learn.count.co/working-in-the-canvas/navigating-the-canvas/keyboard-shortcuts Speed up using Canvas with powerful keyboard shortcuts. ## Cursors In the canvas, the effect of clicking and dragging depends on the current mouse cursor: - Select cursor - select objects by clicking on them, select multiple objects by dragging. Once selected, move or resize objects by dragging. - Scale cursor - when resizing objects, scale rather than resize. Scaling increases text sizes, border radii etc. - Hand cursor - when dragging, pan the viewport ## Navigation ## Object Creation ## Object Editing ## Object selection ## Object interaction ## Cells ### Export code and results URL: https://learn.count.co/working-in-the-canvas/navigating-the-canvas/export-code-and-results You can easily export canvas cells and analysis results in a range of formats for sharing beyond Count. Count understands the structure of your analysis, so any cell can be exported as compiled SQL ready to be executed on your database, or as Jinja-SQL compatible with dbt. - Export compiled SQL and Jinja-SQL - any object in Count can also be exported as an image or PDF, which is a very flexible way to share static content. - Export images and PDF files - additionally, any cell can be downloaded or copied as a CSV file ready to be inserted in a spreadsheet, or uploaded to another tool. - Export CSV files #### Export images and PDF files URL: https://learn.count.co/working-in-the-canvas/navigating-the-canvas/export-code-and-results/export-images-and-pdf-files Export any object as an image or PDF document ## Exporting images To download an image file, just select the objects to be exported and choose the PNG option in the Design sidebar. Clicking the Export button will download a .png file to your computer. Alternatively, right-click any object (or selection of objects) to copy a .png file to the clipboard: ## Exporting frames from a canvas When a frame is selected, an Export PDF button is available in the design bar. Click this button to download a PDF file containing the contents of the selected frame. To download all of the currently visible frames in the canvas, use the Export frames as PDF button from the canvas menu. When exporting all canvas frames: - Each frame will be included as a separate page in the PDF file - Frames that have been hidden will not be included ## Exporting frames from a report When viewing a report, the options to export report frames are accessible from the canvas menu: The available options are: - Export current page as PDF - this option will download a PDF file with a single page containing the current report page. - Export report as PDF - this option will download a PDF file containing all report pages as separate pages. Additionally, any frames that are visible within a report page will be included too. #### Export CSV files URL: https://learn.count.co/working-in-the-canvas/navigating-the-canvas/export-code-and-results/export-csv-files Export any cell as a CSV file. ## Download CSV files After selecting any SQL, Python or visual cell, the option to download results as a CSV file will appear in the floating cell controls. If all cell results are available locally, a CSV file will be generated and downloaded immediately. If the result set is too large to be held locally, Count will execute a new query with no row limit, and the results will be downloaded as a formatted CSV file. (Result size limits of 128MB apply, so if your result set is very large, your download may not contain all rows). This option will not be available if it has been disabled in your workspace settings. If your visual has multiple marks, only the first mark will be downloaded. ## Copy CSV data Right-clicking on a cell (or using the canvas menu in the upper-left) will present the option to Copy as CSV. This action will never execute a new query (unlike the Download CSV option above), but will instead copy the current results for that cell to the clipboard. The copied CSV text will only contain the number of rows that are currently indicated in the cell footer. ## Paste CSV data Once CSV data has been copied, pasting back into the canvas using the keyboard shortcut will create a new CSV cell . This is a useful shortcut to save a copy of some cell results at a certain point in time. ## Spreadsheet data Copied CSV data is designed to be compatible with popular spreadsheet applications, such as Microsoft Excel or Google Sheets. Pasting CSV data from Count into a spreadsheet will add the pasted data as new cells, and pasting copied spreadsheet ranges into Count will add a new CSV cell. #### Export compiled SQL and Jinja-SQL URL: https://learn.count.co/working-in-the-canvas/navigating-the-canvas/export-code-and-results/export-compiled-sql-and-jinja-sql Want to use your SQL somewhere else? We've got you covered. To export the full SQL (including all parent cells) for a particular cell, right-click on the cell and select the Copy as -> Copy as SQL option (or the Export SQL button in the design bar). Exporting SQL requires a canvas analyst role. A new panel will open showing: - A preview of the compiled SQL for this cell - An overview of all of the upstream cells that have been compiled into this export ## SQL + Jinja Selecting this option makes it possible to customise the number of upstream cells included in the exported SQL by selectively treating cells as dbt models. Use this option to generate code that is compatible with dbt. Clicking on a cell in the DAG summary will convert it to a model (indicated by the dbt symbol), which means that all cells further upstream need not be included in the compiled code. Any references to models are also converted to ref() invocations. Depending on the contents of your cells, other changes may be applied to the compiled code (especially if those cells contain more complex Jinja expressions). A summary of those changes is visible by clicking on View code changes. ### Design sidebar URL: https://learn.count.co/working-in-the-canvas/navigating-the-canvas/design-sidebar Make the canvas work for you. The Design sidebar (right-hand side of the screen) contains all the controls for adjusting the look and behaviour of your canvas. You can open/close the sidebar using the arrow button at the top, or with the shortcut Cmd + \ (Mac) / Ctrl + \(Windows). ## Tabs - Design – Controls for appearance, data, connectors, and export. - Alerts – Configure alerts for your canvas. ## Zoom & View Options At the top of the Design tab you’ll see a zoom dropdown with quick access to zoom and display controls: - Zoom in – Cmd/Ctrl + + - Zoom out – Cmd/Ctrl + - - Zoom to fit – Shift + 1 - Zoom to 50% - Zoom to 100% – Cmd/Ctrl + 0 - Zoom to 200%` Additional display options: - Multiplayer cursors – Show or hide collaborator cursors in real-time. - Comments – Show or hide comment indicators. - Dot grid – Toggle a background grid to help align objects. ## Background - Background color – Set the canvas background with a hex code or color picker. - Opacity – Adjust the background transparency. ## Styles Styles let you create shared visual elements you can reuse across your canvas. - Colors – Save local color swatches for quick access. - Categorical palettes – Define palettes for grouping categories consistently. - Continuous palettes – Define gradients for numeric or continuous data. ## Data - Execute cells automatically – Choose whether cells in this canvas run automatically when opened. - If a cell is prevented from executing automatically, it will show a message with an option to manually execute the query. - Caching – The option in this sidebar lets you change the caching settings for your current canvas. - Canvas caching can also be enabled or disabled in workspace settings, where the default caching behaviour is defined. - Learn how to change canvas caching settings here. ## Connectors - Show cell connectors – Toggle connector lines on or off. Connectors indicate when one cell references another. - Note it is also possible to toggle connectors on/off for individual frames. ## Exploring - Allow viewers to explore cells – If enabled, viewers with edit access can interact with cells directly in this canvas. ## Export to templates - Save as template – Export the current canvas setup as a reusable template. ## Top-right canvas controls Above the Design sidebar, you’ll also see additional controls at the top-right of the canvas: - Profile menu – Shows who is currently active in the canvas. - Lock canvas – Switch between unlocked and locked mode: - Unlocked (default) – Everyone shares the same live session, edits and interactions are synced instantly, and mouse cursors are visible to all. Best for collaborative exploration, development work, or workshops where you want everyone to interact together. - Locked – Each visitor has their own independent session. Viewers can still use control cells (filters, dropdowns, sliders, etc.), but changes are temporary and only visible to them. Most objects cannot be edited (except comments and controls). Best for creating shared metric maps, interactive reports, or training canvases where the layout stays fixed but each person can explore the data on their own. - Learn more about locking and unlocking canvases. - Follow a collaborator – Click on someone’s avatar to follow their view around the canvas. Useful during screen-sharing calls, walkthroughs, or training sessions. - Present – Enter presentation view, hiding editing tools to focus on results. - Share – Open sharing settings to invite collaborators or manage permissions. ## Canvas objects URL: https://learn.count.co/working-in-the-canvas/canvas-objects Count's canvas can contain a range of objects, both data-driven and static. A canvas contains a collection of objects. Each object type has its own features and options and you can read more about these in the following pages: - Cells - Text and markdown - Shapes and tools - Sticky notes - Frames - Images and videos - Embeds - Stamps In addition, there are generic operations that can be applied to all (or multiple) objects: - Grouping objects - Layer properties and alignment - Locking objects - Scaling objects ### Cells URL: https://learn.count.co/working-in-the-canvas/canvas-objects/cells Cells = data. Cells are how you interact with data in a canvas. See the links below for documentation on how to create and use the various types of cells available in Count: - SQL cells - Python cells - Visual & low-code cells - Control cells - CSV cells - Local DuckDB cells ### Text and markdown URL: https://learn.count.co/working-in-the-canvas/canvas-objects/text-and-markdown Document your canvases with rich text Text boxes let you add notes, instructions, and documentation to your canvas. They support full text formatting, markdown shortcuts, links, mentions, and dynamic text. ## Inserting a text box - Select the T icon from the toolbar. - Or use the keyboard shortcut: T. ## Formatting your text When you select a text box, formatting options appear in the Design sidebar: - Font family & weight - Font size - Text color - Formatting – bold, italic, underline, strikethrough - Alignment – left, center, right, justify - Vertical alignment – top, middle, bottom - Opacity – adjust transparency of the text ## Inline options While typing in a text box, you’ll see additional inline options: - Link – add a hyperlink to external content. - Dynamic text – insert references that update automatically (e.g. values from cells). ## Mentions and links Use @ to bring up a menu of objects you can tag: - Users – @username creates a user tag. Users receive an email notification when tagged if they have opted in to receive notifications in their user settings. - Frames or cells – @frame-title or @cell-title creates a clickable link to that object. ## Markdown shortcuts When editing a text box, use the following shortcuts to create markdown elements. - # + space → Header 1 - ## + space → Header 2 - ### + space → Header 3 - - + space → Bullet point - > + space → Callout - ``` + space → Code block ## Text keyboard shortcuts - T – Insert a text box - Cmd/Ctrl + E – Inline code format - Cmd/Ctrl + B – Bold - Cmd/Ctrl + I – Italics - Cmd/Ctrl + Control + Space – Emoji picker ### Shapes and tools URL: https://learn.count.co/working-in-the-canvas/canvas-objects/shapes-and-tools So simple, so powerful. Shapes and tools let you add structure, annotations, and diagrams to your canvas. You’ll find them in the toolbar at the bottom of the screen under the shapes menu. Available options (with shortcuts): - Rectangle (R) - Ellipse (O) - Line (L) - Connector (Shift + L) - Pencil (P) (See also: Stamps, Images, and Embeds for additional tools available in the same menu.) Hold Shift while dragging to create perfect squares and circles. ## Rectangles - Select from the toolbar or press R, then click and drag on the canvas to draw. - Hold Shift while dragging to create a square. - Customize fill color, stroke width, stroke color, and corner radius. - Add text directly inside a rectangle (formatted the same way as text boxes). ## Ellipses - Select from the toolbar or press O, then click and drag on the canvas to draw. - Hold Shift while dragging to create a circle. - Customize fill color, stroke width, and stroke color. - You can also type text directly into ellipses (formatted the same way as text boxes). ## Lines - Select from the toolbar or press L, then click and drag on the canvas to draw. - Hold Shift while dragging to constrain the line to 45° increments (0°, 45°, 90°, etc.). This is useful for perfectly horizontal, vertical, or diagonal lines. - Customize stroke width, color, endpoints and stroke dash - read more about custom stroke dashes here. ## Connectors Connectors are dynamic lines that “stick” to objects: if you move the objects, the connector follows. - Insert from the toolbar with Shift + L, then drag endpoints to objects. - Or: select an object and click the + button to auto-create a connected copy. - Adjust connector attachment points by dragging endpoints. - Customize width, color, endpoints, and whether the connector is straight or rectilinear. ## Pencil - Insert from the toolbar or use P. - Draw freehand by holding the mouse/trackpad while moving. - Customize stroke width and color. ### Sticky notes URL: https://learn.count.co/working-in-the-canvas/canvas-objects/sticky-notes Jot down those ideas before they disappear. Sticky notes are core to the collaborative and iterative nature of the canvas. They’re lightweight, flexible objects you can use to: - Brainstorm ideas with your team before starting a piece of work - Make notes to yourself about why you chose to do an analysis a particular way - Keep track of an ongoing to-do list - Sort ideas into groups - Gather feedback from stakeholders ## Insert a sticky note - Select the sticky note icon in the toolbar, or press S. - Then click on the canvas to place it. - Sticky notes can be moved at any time by clicking and dragging. ## Edit a sticky note - Add rich text (bold, italics, strikethrough, inline code). - Use markdown shortcuts (see Text and Markdown for details). - Change the background color. - Add emojis to make them more expressive. Other users can edit sticky notes live, making them perfect for collaborative sessions and workshops. ## Adding your name By default, the sticky note you create will display your name in the bottom right. - You can toggle this off to make a note anonymous. ## Resizing sticky notes Unlike other objects, when you resize a sticky note its content scales proportionally. Sticky notes are best for brief comments. Consider Shapes or Text Boxes as an alternative if you have a lot to say! ## Deleting a sticky note Select the sticky note and hit backspace to delete. ### Frames URL: https://learn.count.co/working-in-the-canvas/canvas-objects/frames Organize your canvas with frames. Frames are a powerful way to organize and structure your canvas. They let you: - Group related objects together for easier organisation. - Define presentation-ready sections of your work, frames are the basis of what’s displayed in Present view. - Hide frames to reduce clutter, and show them only when needed. A common use case is to separate your canvas into planning, analysis, and findings frames. This makes it easier to work collaboratively, while keeping the end output clear and polished. ## Creating frames There are two ways to create a frame: - Insert from toolbar – Select the Frame tool or press F, then click and drag on the canvas. - Frame selection – Select an object or group of objects, then right-click > Frame selection, or use the shortcut Cmd + ⌥ + G (Mac) / Ctrl + Alt + G (Windows). Objects covered by a newly created frame are automatically added to it. ## Managing contents - Add objects by dragging them inside the frame boundaries. - Remove objects by dragging them out. - When an object is about to be added, the frame border will highlight. - Not sure if something is in a frame? Move the frame — if the object comes with it, it’s inside. ## Moving a frame - Select the frame by clicking its name label or empty space inside its border. - Drag to move the frame and all contained objects. - Clicking directly on an object inside will move that object only. - Drag the frame edges or corners to resize it. ## Hiding a frame - Select the frame and click the eye icon to hide its contents. - A hidden frame leaves only the handle visible. - Click the eye icon again to un-hide. ## Formatting frames Frames have additional formatting options in the design sidebar: - Corners – Adjust the corner radius. - Fill – Set a background color and opacity. - Stroke – Set a border color, opacity, and width. - The stroke color also defines the background color of the frame title. - Opacity – Adjust the overall transparency of the frame. ## Frame controls & permissions In the design sidebar, additional frame controls are available: - Show/hide the frame contents. - Show/hide cell connectors within the frame. - Lock or unlock the frame. Analysts can also restrict these controls so only analysts can modify them. For example, an analyst may: - Add a complex analysis inside a frame. - Hide and lock the frame. - Restrict editing to analysts. Other users will only see the frame handle and cannot open or change it. ## Using frames for database management Cells hidden in frames won't re-run unless a cell outside the frame depends on it. If you have completed some self-contained analysis, this can be a good way of 'storing' those cells while ensuring they don't refresh to optimize canvas performance. ## Exporting and templates - Frames can be exported directly as PNG images. - Frames can also be saved as templates, making them reusable in other canvases. ## Limitations - Frames cannot contain other frames. - If a frame overlaps another, they remain separate. - However, in reports: if a frame spatially contains another frame, both may appear (hidden frames included), allowing readers to optionally reveal more context. ### Images URL: https://learn.count.co/working-in-the-canvas/canvas-objects/images See how to spice up your canvases with images. You can add images directly to your canvas to illustrate ideas, provide context, or enrich your analysis. ## Inserting an image There are several ways to insert an image into the canvas: - Toolbar menu — Select Upload image… from the shapes menu. - Paste shortcut — Copy an image to your clipboard and paste it directly (Cmd + V on Mac / Ctrl + V on Windows). - Drag and drop — Drag an image file from your computer onto the canvas. Supported formats: GIF, JPEG, PNG, SVG, WebP Maximum file size: 10MB ## Editing an image Once inserted, images can be: - Resized — drag the corners to scale. Hold Shift to maintain the image’s proportions. - Positioned — use Bring to front / Send to back to adjust layering with other objects. ### Embed URL: https://learn.count.co/working-in-the-canvas/canvas-objects/embed Embed content from across the web. Embeds let you bring external content directly into your canvas. This means you can collaborate with tools like Looker, Google Docs, Figma, YouTube, Loom, Tableau and many others without leaving Count. ## Creating an embed There are several ways to add embedded content: - Toolbar — Select Embed link from the Shape menu. - Paste URL or iframe — Paste a supported link or iframe snippet directly into the canvas. Count will attempt to unfurl the link and check whether it can be embedded. ## How links are displayed Depending on the link, Count will render it as: - Embed – The content is shown directly in the canvas (e.g. a YouTube video or Figma file). - Bookmark – If the link can’t be embedded but metadata can be fetched, Count shows a card with a title, description, and preview image. - Text link – If metadata can’t be fetched, the raw link is displayed. ## Viewing and interacting When you click View, the embed becomes active. While active and selected, an embed toolbar appears above it with additional options: - Maximise – Expand the embed to full screen. - Convert to bookmark – Change the embed into a bookmark card. - Deactivate – Stop the embed. ## Special cases Tableau requires a slightly modified URL for embedding: - In Tableau, go to Share > Get URL. - Copy the URL, then add this string to the end: ?:showVizHome=no&:embed=true - In Count, select Embed link and paste the modified URL. ### Stamps URL: https://learn.count.co/working-in-the-canvas/canvas-objects/stamps Acting is reacting. Stamps are a quick way to give visual feedback on a canvas. They work like sticky reactions, letting you show approval, flag something for review, or highlight areas for discussion. ## Inserting a stamp - Select Stamp from the toolbar (shortcut: U). - Choose an emoji and click on the canvas to place it. - You can also place a stamp directly on top of another object (e.g. a chart or note). ## Stamp options The available stamps and suggested use cases are: - 👍 👎 — Quickly approve or disapprove an idea. - 😀 😕 — Show positive or critical sentiment. - 🎉 — Celebrate progress or wins. - ❤️ — Highlight a favorite idea or important point. - 🚀 — Mark items with high potential or priority. - 👀 — Flag something for closer review. - ⭐ — Call out something outstanding or recommended. - ❓ — Raise a question or indicate uncertainty. - 🔢 — Rank or vote on multiple options. ## Resizing a stamp - Click and drag corners to resize. ## Removing a stamp - Select the stamp and press Backspace/Delete. For more emojis, use the system emoji menu (Cmd + Ctrl + Space on Mac, Win + . on Windows) when adding text to the canvas. ### Grouping objects URL: https://learn.count.co/working-in-the-canvas/canvas-objects/grouping-objects How to edit your canvas like a pro. Grouping objects lets you treat multiple items as a single unit. This makes it easier to move, resize, align, or duplicate them together. Unlike frames, groups don’t provide names, visibility toggles, or reporting features — they’re purely for lightweight organization. ## Creating a group - Select two or more objects on the canvas. - Right-click and choose Group selection, or use the shortcut: - Mac: Cmd + G - Windows: Ctrl + G ## Ungrouping - Right-click on the group and select Ungroup. - Or use the shortcut: - Mac: Cmd + Shift + G - Windows: Ctrl + Shift + G ## Frame vs Group - Group: Best for quick edits — move/resize/duplicate objects together. - Frame: Best for structured organization, hiding content, and preparing presentable sections. ### Object order and alignment URL: https://learn.count.co/working-in-the-canvas/canvas-objects/object-order-and-alignment Become a canvas master. Objects on the canvas are layered in a stack. You can change the stacking order to control which objects appear in front of or behind others. To adjust order, right-click on an object and choose: - Bring to front (]) – moves the object above all others. - Bring forward (Cmd + ] / Ctrl + ]) – moves the object one step forward. - Send backward (Cmd + [ / Ctrl + [) – moves the object one step backward. - Send to back ([) – moves the object behind all others. ## Alignment Multiple selected objects can be aligned or distributed evenly using the alignment tools in the right-hand Design sidebar. Options include: - Align left, center, right - Align top, middle, bottom - Distribute horizontally or vertically ### Locking objects URL: https://learn.count.co/working-in-the-canvas/canvas-objects/locking-objects How (and when) to lock your objects. In addition to locking a whole canvas, you can also lock specific objects or groups of objects. When an object is locked: - It cannot be moved, resized, or edited until it is unlocked. - Other users can still interact with unlocked objects normally. - This helps protect important elements while keeping the rest of the canvas flexible. ## Why lock objects? - Prevent accidental edits to key diagrams, labels, or frames. - Preserve layout and structure while letting teammates add notes or annotations. - Keep “reference” elements fixed in place while iterating on other content. ## How to lock objects - Select an object (or group of objects). - Right-click and choose Lock/Unlock. Shortcut: - Mac: Cmd + Shift + L - Windows: Ctrl + Shift + L ## How to unlock objects - Right-click the object and select Lock/Unlock. - To unlock everything at once, right-click and select Unlock all objects. - Or, select a locked object and click the padlock icon that appears above it. ## Special case: locked frames If a frame has been locked and restricted to analysts only, only analysts can unlock it. This helps safeguard complex analysis sections. ### Scaling objects URL: https://learn.count.co/working-in-the-canvas/canvas-objects/scaling-objects How to scale objects in the canvas. ## Scaling - Always proportional — the object and all its contents increase or decrease together. - For example, scaling a visual enlarges axis labels, titles, and data points at the same time. - Use the Scale cursor from the toolbar or the K keyboard shortcut. ## Resizing - Only changes the bounding box, without altering the proportions of internal contents. - For example, resizing a visual stretches the space it takes up, but the labels and points remain the same size. - To resize, drag the corners or edges of the selected object. ## Precision control For exact placement and dimensions, use the numeric fields in the sidebar: - X / Y – Position of the object on the canvas. - W / H – Width and height. - θ (theta) – Rotation angle in degrees. This is especially useful for creating report-ready layouts where consistency matters. ### Shared styles URL: https://learn.count.co/working-in-the-canvas/canvas-objects/shared-styles Define once, use everywhere. Shared styles let you keep colors and palettes consistent across your canvas — and, if you’re on an Enterprise plan, across your whole workspace. ## Manage styles - Create styles - With nothing selected, click the Add (+) icon next to Styles in the right sidebar. - You can create shared colors, categorical palettes, and continuous palettes. - Once created, edit the name and properties from the sidebar. - Use styles - Shared colors appear under the Shared tab in the color picker. - Shared palettes appear at the top of the palettes list. - Edit styles - Click the color thumbnail next to a style to change it. - Any updates are applied instantly to all objects using that style. - Delete styles - Click the Delete icon in the sidebar. - Objects keep their current properties but are no longer linked to the deleted style. ## Examples of style types - Single color → best for items that take one fill or stroke, like simple charts, shapes, or text. Example: define a shared “Highlight yellow” to quickly emphasize key findings across canvases. - Categorical palette → used when values fall into discrete groups. You can also drag colors to change the order they’re applied. Example: use a 5-color brand palette for sales regions (North, South, East, West, Central). - Continuous palette → applied when values fall on a numerical scale. Example: use a green → red gradient for profit margin, so higher values show in green and lower in red. ## Workspace styles (Enterprise only) Workspace styles extend shared styles across multiple canvases and projects: - Create shared styles in a canvas. - From the File menu, select Publish shared styles to workspace… - Confirm if publishing will overwrite existing workspace styles. Workspace styles don’t appear in the design sidebar — they’re available anywhere local color/palette options are displayed. Overwriting or removing workspace styles may cause objects to revert to default colors. I created a shared color/palette, but it doesn’t appear in the style picker for my object. Styles are context-specific, which means you’ll only see the ones that apply to the object you’re editing: - Single colors → available for objects that take one fill or stroke (e.g. charts with a single color applied, shapes, text). - Categorical palettes → available for charts with discrete categories (e.g. bar charts split by region). - Continuous palettes → available for charts with numeric scales (e.g. a heatmap or scatterplot with a gradient). If the style you’re looking for isn’t relevant to that type of object, it won’t be shown. ## Collaborating and Sharing URL: https://learn.count.co/working-in-the-canvas/collaborating-with-your-team Work through problems with your team in real time, and control exactly who sees what. ### See changes as they happen Count is built for teams working through a problem together, not for one person working alone. Multiple people can be in the same canvas at the same time, seeing each other's changes as they happen, rather than working in isolated copies that need to be reconciled later. When something needs discussion rather than a change, comments let you leave notes and tag colleagues directly next to the query, chart, or cell being discussed, so context never gets lost in a separate chat thread. ### Share your work without losing control Sharing your work is just as important as making it. Shared links and embeds let you put a canvas in front of people who aren't in Count at all, whether that's a stakeholder who just needs to view a result or a wider audience seeing it embedded in another tool. Sharing permissions give you fine-grained control over who can view, comment, or edit a given canvas, so opening something up to a wider audience doesn't mean giving up control over it. You can also keep the team looped in with Slack notifications when something changes, so nobody has to remember to check back in themselves. ### Real Time Collaboration URL: https://learn.count.co/working-in-the-canvas/collaborating-with-your-team/real-time-collaboration Better together Real-time collaboration is at the heart of what makes the Count canvas unique. Many people can work together in the same document, contributing their skills and talents whether they are a business or data person. In the upper right of the canvas is a list of everyone currently viewing the canvas (including anonymous users if your canvas is public): Clicking on any person will put the canvas into 'follow mode', which keeps your view in-sync with the person you are following. ## Real-time and locking It's important to understand what real-time means in the context of the Count canvas, as there are important implications for user experience. A canvas has two states: ## Unlocked (default) Everyone who visits the canvas at the same time shares a single session and all canvas features are enabled. Each action is displayed simultaneously to all participants. The mouse cursors of other users are displayed live. Any changes are saved automatically. When you are collaborating with your team, doing development work or exploring findings together, you want your canvas to be unlocked. ## Locked Everyone who visits the canvas at the same time has an independent session. Viewers can still use control cells, but as they are in separate sessions they can select separate things. Most objects cannot be interacted with, except for commenting and editing control cells. Changes to control cell selections are not saved, and are only visible to you. The canvas toolbar shows more limited options related to navigation and commenting. Locking a canvas does not affect how your queries are executed - only caching can affect that. When you are creating a static document or report that will be used by many people or needs to be uneditable, you want your canvas to be locked. To make changes to a locked canvas or report without interrupting viewers, duplicate it and merge your changes. ## How to lock/unlock a canvas In the canvas menu you'll see the option to Lock canvas or Unlock canvas. You can also find this option in the drop-down menu from your avatar in the top-right corner of the screen. ### Comments URL: https://learn.count.co/working-in-the-canvas/collaborating-with-your-team/comments Look alive, team! Use comments to tag other users in your canvas. ## Adding comments Anyone can add comments to a canvas or report, as long as they are at least a guest or member of the workspace. - To add a comment in a canvas, click the comment icon in the canvas toolbar, or use the keyboard shortcut C, then click anywhere on the canvas to drop a comment. - Canvas comments are 'sticky' and will remain attached to the object they were dropped on. Comments can be moved to new objects by clicking and dragging them. ## Mentions When writing a comment, you are able to mention any member of the workspace by typing the @ key - a searchable autocomplete list will appear. - Press the Tab or Enter keys, or click an option to add a mention to your comment. Info callout If you are a workspace guest, you are only able to mention workspace members already present in the comment thread. ## Comment notifications When submitting a comment, the following users will be sent an email: - The creator of the canvas - Anyone who has contributed a version of the canvas - Anyone who has commented in the current conversation - Anyone that is mentioned in your comment If a user is no longer able to view the canvas they will not receive an email notification, even if they are mentioned. To stop receiving email notifications about comments, disable them from the canvas menu: ## Viewing comments To view all comments in a canvas, click the comment icon in the canvas toolbar, and the comments sidebar will open on the right. Click on a comment to navigate to it in the canvas. ## Resolving threads When viewing a comment in the canvas, clicking the tick icon will resolve the thread: This will move the comments in this thread to the Resolved section of the comment menu, but will not delete them. ## Deleting threads To delete the entire comment thread, choose the Delete thread option from the thread menu: ### Permissions for sharing a canvas URL: https://learn.count.co/working-in-the-canvas/collaborating-with-your-team/sharing-permissions Configure who can see and edit your canvases and reports We recommend checking out our docs on roles as a complement to this section on sharing. ## Roles per level As a quick reminder, here are the possible roles at each level and a reminder that the most permissive role that a user has in any of the 3 levels will be their active role for all levels. E.g. if a user is assigned a viewer role at a project level, and an editor role for one of the canvases in that project, that user is reassigned an editor role at the project & workspace level as the most permissive role always wins. ## Sharing The sharing menu in the top right corner of a canvas provides a lot of flexibility for how the canvas can be shared. Depending on which workspace and project settings are active, there are several ways a canvas can be shared. ## Sharing with the whole workspace Enabling this option from the sharing menu in the canvas allows any workspace member (except workspace guests) to view both the canvas and/or report. If the project is already shared with the workspace, then this option is disabled as it will have no effect. If a user is a member of a workspace but not of the project where a canvas lives, then they will find the canvas in the Shared menu in the workspace. The "share with workspace" option on the sharing menu of a canvas is only available to project members if the Allow Sharing option is enabled in the project settings, otherwise it is only available to project admins. To enable this click on manage project in the right hand side of the project screen. Once in the settings, toggle Allow sharing on. ## Sharing with everyone in the project By default, the permissions that project members have for the canvas are determined by their project role. For example, if someone has an editor role for the project, then they will also have a editor role for the canvas. In case the project role is too permissive, you can apply additional restrictions to it by changing the option selected here in the sharing menu in the top right of the canvas. All project users, as one bloc, can be assigned canvas specific permissions to edit low code cells only, to edit ## Sharing with a person Anyone with access to a canvas can share it with others by entering the other person's email address or name if they're a member of the workspace. If the invited users aren't members of the workspace they will become workspace members (if their email address is whitelisted) or workspace guests (if workspace guests are allowed). The invited users will receive a notification email linking them to the canvas directly. If the invited users are workspace members but not members of the project, they will find the canvas in the Shared menu in the workspace (see Sharing with the whole workspace above). This sharing option is available to project members if the Allow Sharing option is enabled in the project settings (see Sharing with the whole workspace above), otherwise it is only available to project admins. ## Mixing canvas and project/workspace roles If a canvas is shared with a named person via email or name as seen above, that role may take precedence over any project or workspace roles. For example, suppose: - Sarah is a workspace member - Sarah is also a project member with the viewer role - The canvas is shared with the project Then Sarah will have a viewer role in the canvas due to their project membership, and the fact that the canvas is shared with the project. If Sarah is then given an explicit editor role in the canvas, they will be able to edit the canvas even if they are only a project viewer. In the converse case, if a user is given an explicit canvas role that is overridden by a more permissive role elsewhere, a warning will be displayed in the canvas share menu e.g. a user has been explicitly assigned a viewer role in a canvas. They are then assigned an editor role at project level. This triggers a warning in the sharing menu of the canvas. ## Sharing on the web Enabling this option allows anyone to view the canvas, even if they are not signed in to Count. You can select to share both the canvas and the presentation, or just the presentation (the report mode view of the canvas). To share on the web like this, sharing public links needs to be enabled in workspace settings as shown below. Similarly, the option to share on the web is only available to project viewers or editors if the Allow sharing option is enabled in the project settings, otherwise it is only available to project admins. ## Sharing a report If you create a report, you can choose to share the report but not the canvas by selecting the Can view report only option. Anyone with this role will see an error if they try to navigate to the canvas URL. ## Permissions preview If you have an Analyst role in a canvas, you can choose to preview the canvas as another role from the canvas menu in the top left of your canvas screen. This is helpful when understanding how your canvas will look to other members of your workspace, and which actions will be allowed or not. To exit the preview, select the same option again from the menu, or click the close icon in the floating notification banner. ### Shared Links URL: https://learn.count.co/working-in-the-canvas/collaborating-with-your-team/shared-links Show people exactly what you mean using focused links that jump them straight to the point. A normal canvas URL looks like https://count.co/canvas/. The default view of this canvas can be modified however, by generating and sharing special links. These link types are: - Report links - Version links - Object links - View links ## Report links A report link looks like https://count.co/report/, and causes the canvas to open in the report view. Report links are generated automatically when navigating to a report - just copy the link from the URL bar of your browser, or click the Copy link button in the sharing menu (top right corner) while viewing a report. A report link will point to the first frame in a report by default. To link to a specific frame of the report, copy the link from the URL bar while viewing that frame - it should look like https://count.co/report/?frame=. ## Version links A version link looks like https://count.co/canvas/?version=, and causes the canvas to open at a particular version from the version history. Copy links to versions from the version history menu accessed from the canvas menu on the top left. ## Object links An object link looks like https://count.co/canvas/?object=, and can be generated by right-clicking on any object and choosing Copy link: If this link is opened by anyone else, they will navigate and zoom to that object when the canvas loads. Object links do not hide other parts of the canvas, they just change the default canvas viewport. To create a link to a larger portion of a canvas, one option is to use a frame to delineate the desired region, then share a link to that frame. ## View links When a canvas is locked, changes to control cells are not saved. To share the current values of your control cells with someone else, generate a canvas view link from the sharing menu, when the canvas is locked. Anyone using this link to reach the canvas will see the most up-to-date version of that canvas, but with the values of the control cells set to what they were when you generated the link: View links can only be generated and used when the canvas is locked, so if the canvas is subsequently unlocked, a warning message will be displayed and the view ignored. ### Embedding Canvases URL: https://learn.count.co/working-in-the-canvas/collaborating-with-your-team/embedding-canvases Embed interactive canvases into any webpage that supports iframes. Canvases can be embedded into any website or app that supports iframes, such as Notion, Miro or FigJam. To do so, open the Share menu in the canvas, and select Embed code. Then simply copy the iframe code into the other site and you're all set. If embeds are disabled in your workspace settings, this button will not be visible. Control cells can be edited in embedded canvases, which will cause any linked cells or visuals to update (as in Count itself). However, these changes are not shared with others, even if the canvas is unlocked. ## Embed reports Embedding reports works in exactly the same way as canvases. Just head to the Share menu in a report and select Get embed. To create an embed of a single frame, just create a report with a single frame and copy the embed code for the report. ## Permissions in embeds Access to embeds is controlled by the same permissions model as the rest of Count. For private canvases, users will need to be signed in and authorized to view the canvas. (They'll be given an option to sign in if they're not already.) If you'd like to embed a canvas that can be seen by anyone, remember to select Share to web from the Share menu in the canvas. Warning: It's not possible to access private embeds from native/desktop applications. If you'd like to add embeds to these apps, you must select Share to web first. ### Slack integration URL: https://learn.count.co/working-in-the-canvas/collaborating-with-your-team/slack-integration Getting alerts in Slack Note: Using the AI Agent from Slack This page is about setting up and receiving Count notifications and alerts in Slack. You can also use Slack to interact with Count's AI Agent. See here for details. ## Install the Count app for Slack To send alert messages to a Slack channel, you will first need to install the Count app for Slack. Install the app by visiting your user account settings and clicking the Connect Slack button. Once the app is installed, you will be able to select Slack channels as alert destinations in a canvas. Read about how Count uses your data in our Privacy Policy. ## Use the Count app for Slack - To view all canvases that are sending alerts to a Slack channel, type /count list in the channel - To remove a canvas from a channel, type /count list and click the Delete subscription button. ## Send alerts to private Slack channels To access private Slack channels, you may need to subscribe to a canvas from Slack rather than Count. To do this: - Go to the private channel - Invite the Count app for Slack by typing /invite @count - Open the subscriptions dialog by typing /count subscribe - Choose the canvas you want to subscribe to from the list (you will need permission to edit the canvas) ## Troubleshooting If you encounter any difficulties using the Count app for Slack, please contact Count support using the in-app chat, or by emailing us at support@count.co. ### Row-level security: Identity-Aware Reports URL: https://learn.count.co/working-in-the-canvas/collaborating-with-your-team/identity-aware-reports Identity-Aware Reports let you share a single canvas with many people and have each person see only the rows they're allowed to see - row-level security, defined and enforced in Count. Identity-Aware Reports let you share a single canvas with many people and have each person see only the rows they're allowed to see - row-level security, defined and enforced in Count. You write the rule once, in SQL, using the viewer's email, and Count recompiles the query for whoever opens the canvas. Note: Enterprise feature Identity-Aware Reports are an Enterprise feature. Please speak to a member of the Count team to discuss enabling them for your workspace. ## How it works Two attributes are available in the `count` Jinja namespace in SQL cells: count.user_email is already quoted and escaped for you - don't wrap it in quotes. Because the values differ per viewer, each viewer gets their own compiled query and their own cached result. Nobody sees another viewer's cached rows. ### Why locking matters Identity-Aware Reports only resolve an identity on a locked canvas. On an unlocked canvas count.user_email is NULL for everyone, so that editors don't each get a different result while working on the canvas together, and so that the result cache stays shared. Locking is also what makes the rule enforceable: viewers of a locked canvas can't edit the SQL, so they can't remove the filter. ## Writing an identity-aware query Filter in the SQL cell that queries your database, so the database only ever returns the permitted rows: For a permissions table that lists who may see each row: The if count.is_locked else ... fallback controls what editors see while the canvas is unlocked. Pick it deliberately: - a placeholder email → editors see one representative viewer's slice - a literal that matches nothing → editors see an empty result and build against the shape only Use Show compiled SQL on the cell to check what actually runs. Note: Filter in remote database queries Put the identity-aware filter in the cell that queries your database - not downstream of it. A remote database cell sends its query to your warehouse, so unpermitted rows never reach the browser. If you instead load the full table and then filter it in a local cell, a Python cell, or a visual's filters, the complete dataset has already been fetched to the canvas and is available to anyone with access to it. The same applies to hiding results visually. Hidden frames, locked objects, and off-screen cells are presentation tools, not security controls - they don't stop someone with canvas access from reaching the underlying data. ## Restricting viewer access Because the filter only applies while the canvas is locked, you must stop viewers from opening it unlocked. Turn on Only accessible when locked in the canvas's Document settings (right sidebar, analysts only). With it on, anyone without edit access is denied access to the canvas entirely while it is unlocked. Editors and analysts are unaffected. If a cell uses count.user_email and this setting is off, Count shows a Viewer access not restricted warning on the cell. Treat that warning as a blocker - until it's resolved, any viewer can open the unlocked canvas and see unfiltered results. ## Checklist for a secure report 1. The filter lives in the SQL cell that queries the database, not in a downstream local / Python / visual filter. 2. Every cell that exposes restricted data is filtered - including cells feeding other cells. 3. Only accessible when locked is on, and no cell shows the "Viewer access not restricted" warning. 4. The canvas is locked before you share it. 5. You've verified the result as a viewer (a test account in your permissions table, or the permissions preview) - not just as an analyst. ## Limitations - Locked canvases only - Unlocked, count.user_email is NULL. - Rules are defined in Count, not your warehouse - Queries still run through your connection's shared credentials, so warehouse-side row-level policies attached to individual users don't apply. - No identity outside a signed-in session - Shared links, embedded canvases, and anything running as a service account have no user email, so count.user_email renders NULL. Use signed-in workspace access for identity-aware reports. - SQL cells only - count isn't available in catalog files, and catalogs don't support Jinja templating. - Email only - Custom user attributes and group-based rules aren't supported yet. - The AI agent is disabled on locked canvases, so viewers can't use it to query around the filter. ## Reports and Alerts URL: https://learn.count.co/working-in-the-canvas/reports-and-alerts Turn your analysis into polished reports and stay on top of your data with automated alerts. ### Turn any canvas into a live report Once your analysis is ready, Count makes it easy to share the result rather than the process. A canvas doesn't have to stay a working space; it can become the finished product. Turn any canvas into a live report or a set of slides that updates automatically as the underlying data changes, so the people you share it with are always looking at the current picture rather than a snapshot that goes stale the moment it's sent. ### Sometimes you need something more static Export a clean image or PDF when you're sending a summary outside of Count, or when a report needs to be archived or attached to an email rather than linked to. And when a metric matters enough that you shouldn't have to remember to check it, set up alerts and subscriptions so the right people are notified automatically the moment something moves. ### Reports And Slides URL: https://learn.count.co/working-in-the-canvas/reports-and-alerts/reports-and-slides How to share canvases in presentation and reports Count supports presenting canvases in two ways: • Reports: Scrollable frames with an easily accessible navigation bar that allows for more complex and taller, document-style layouts. • Slides: Fixed frames with a dark user interface for showing your canvas as slides is perfect for presenting on screen or making fullscreen "information radiator" views. To begin, ensure that you have at least one frame, and then click Present in the canvas navigation bar. To exit, click Back to canvas, or use the Esc keyboard shortcut. ## Settings In the top right of the screen is a button to control the view options: - Report / Slides - toggles between the two presentation methods. - Shown in report - choose which frames appear. Drag frames up or down to reorder. - Hidden in report – frames that won’t appear in the report. - Unavailable for report – frames that are either: - Nested inside another frame (the contents will still display within the parent, but the frame itself cannot be selected), or - Explicitly hidden from the report. - Default view – You can control how the report opens for viewers by setting a default view. This ensures that when people open your report, it displays in the way you intend — whether that’s a high-level overview (Fit to screen) or a more detailed, close-up view (Actual size or Custom). - Fit to screen – scales the frame so the entire canvas fits inside the viewport. - Fit to width – scales to fill the available width (recommended for most dashboards). - Fit to height – scales to fill the available height. - Fill screen – expands the canvas to fill all available space. - Actual size – displays the canvas at 100% zoom. - Custom – allows a specific zoom level to be set. - Show report by default - links to this canvas from your workspace will default to the report URL When in the slides presentation mode, the following additional settings are shown: - Autoplay - enable auto-cycling through frames in this report. This is helpful if your report is designed to be viewed passively - Time per frame - the time before the next slide when autoplaying ## Sharing slides and reports Clicking the Share button while viewing a report opens the Share menu - Selecting Share to web shares the report publicly, with options to share both the canvas and presentation, or the presentation only. - To share reports with people but not canvases, ensure that the Can view presentation option is selected. Note: Info Note that other workspace members may be able to view the canvas if the canvas is shared with the project or workspace, or if the project is shared with the workspace. ## Commenting You can comment on reports just as you do in canvases: - Use the C shortcut, or click the comment icon in the navigation bar. - Any workspace member or guest can leave comments. - Comments outside report frames aren’t visible in the report view, but remain in the canvas. ### Alerts and subscriptions URL: https://learn.count.co/working-in-the-canvas/reports-and-alerts/alerts-and-subscriptions How canvas alerts and subscriptions work, and how to add them to your canvas. Alerts let you and your team stay informed without needing to open a canvas. At scheduled times, Count captures the latest results and sends them via email or Slack, so you can keep stakeholders up to date automatically. ## What can be alerted? Alerts can be created from three types of objects: - Cells or visuals – sends an image of the cell or chart, including any visible inputs and outputs. - Frames – sends an image of everything inside the frame (the frame border itself is excluded). - Reports – sends one image for each report frame. When an alert runs, Count re-executes the necessary queries in your canvas and then sends screenshots to the chosen destinations. ## Creating an alert You can add alerts from: - The floating controls on a cell, visual, or frame. - The Alerts tab in the right-hand sidebar using the + button. Once created, all alerts for the canvas are listed in the Alerts sidebar. ## Scheduling alerts ### Default schedule Each canvas has a single default alert schedule that all alerts follow. This is set in the Alerts sidebar. - Choose from simple options (hourly, daily, weekly, etc.). - For more advanced timing, use 'Custom' and a cron expression. - Example: 0 8 * * 1-5 → sends alerts at 8AM every weekday. Alerts can run up to once per hour. More frequent cron schedules will be rejected. Alerts respect your canvas caching settings. Make sure your cache duration isn’t longer than your alert frequency, or you may see old results in your alerts. Individual alerts can override the default by defining their own schedule. This is done by accessing the Configure alert menu next to the alert name: ### Subscribers From the Alerts sidebar you can add and manage who receives alerts. ### Who can subscribe - Workspace members – receive alerts by email, and optionally via Slack if their Slack account is connected. - Workspace groups – if enabled, alerts are sent to all members. - Slack channels – alerts are posted directly to a channel (requires Slack connection). - Email addresses – alerts can be sent to external emails. Additionally: - If a subscriber does not have permission to view the canvas, they will not receive alerts unless public alerts are enabled in workspace settings. In this case a warning message will be displayed (see below) - If subscribers receive an alert and do not have a Count account or access to that canvas, then the alert will not include a link to the canvas. ### Managing subscriptions - Use the checkboxes to choose which alerts a subscriber receives. - Use the subtract icon to remove a subscriber. - By default, subscribers also get error reports if an alert fails. You can toggle this off. - Individual users can opt out from their canvas menu and will not appear in the alert subscribers list. ## Alert options Click the settings icon on any alert to configure options: - Trigger – conditions under which the alert should send (see below). - Custom schedule – override the default schedule. - Include data – if enabled, for a cell or visual alert include a link to a CSV file containing up to 10,000 rows of the data for that cell or visual. If the canvas is deleted, this link will stop working. - Include PDF - if enabled, include a PDF copy of the alert as an email attachment or Slack message reply. (Available on Scale plans and higher.) - Disable alert – turn off the alert without deleting it. - Custom message - include a custom message alongside this alert (see below). You can also reorder alerts in the sidebar — this order determines the order of alerts in the notifications that are sent. ### Custom alert messages Custom messages can be added to alerts as rich text. Click the Add message button to open the custom message editor, which accepts rich text formats, code blocks, lists and links. Use normal markdown shorthand and keyboard shortcuts to format text. Custom messages are added to alert notification emails and Slack messages as rich text just above the alert image output. ### Alert triggers Triggers control when an alert actually fires. For alerts on cells, the condition will relate to the cell itself. For frames or reports, the condition can relate to any cell in the canvas. Options include: - None – always send at the scheduled time. - Rows returned / No rows returned – trigger only if a query does/does not return rows. - Query error / Query does not error – trigger based on query success or failure. - First row matches value – trigger if the first row in a column matches a set value (text, number, or null). ## Testing alerts Use the Test button in the Alerts sidebar to send a sample notification. - Test alerts respect subscriber settings, so you can confirm delivery. - If a trigger condition isn’t met, the alert will still be listed with a message explaining why it didn’t fire. ### Troubleshooting Why isn’t my Slack channel appearing? Private channels may not show in the list. In this case, run /count subscribe directly in the private channel and select the canvas from the list. Why did my alert time out? Queries must finish within 10 minutes. Try: - Simplifying or optimizing the query. - Scheduling alerts at off-peak times. - Enable scheduled queries for your canvas, and configure the query schedule such that queries are executed before alerts are scheduled. This will allow any long running queries to complete and the results cached before an alert is triggered. When the alert is the triggered the cached results will be used instead of executing a new query. Why didn’t I receive the email? - Check your spam folder. - Confirm your address is listed in the alert subscribers (if you are an analyst). - Ensure you haven’t disabled notifications in your account settings. - Ensure you haven’t opted out of this canvas’s alerts. Why are my alerts delayed? Alerts may take 15–20 minutes to arrive depending on load. If delays are frequent, schedule them at a less busy time. Why does my alert contain old results? Alerts use canvas caching. If caching is set to a long duration, results may be reused instead of re-run. Adjust the cache settings to ensure alerts always show fresh results. What does my alert test result mean? • Subscriber Options Applied: All the subscriber options you've configured for that alert will be applied during the test. This allows you to confirm that the correct subscribers will receive the notification. • Trigger Evaluation: If the alert has a trigger condition set, Count will evaluate whether that condition is currently met. • Notification Behavior:Trigger Not Met: If the trigger condition is not met during the test, the test alert notification will still include this alert but with a message indicating that the trigger was not satisfied. This ensures you know the alert configuration is working even if the data doesn't currently meet the criteria.Trigger Met (or No Trigger): If the trigger condition is met (or if the alert has no trigger), a test notification containing the alert's content will be sent to all selected subscribers. Use the test button to ensure your alert subscribers and trigger logic are set up as expected. ### Data Snapshots URL: https://learn.count.co/working-in-the-canvas/reports-and-alerts/data-snapshots How to save your work...and your data! To save a version of your canvas with all of the current query results, use data snapshots. ## How to enable data snapshots To create data snapshots, first enable either Static or Scheduled query caching. See the following page for more information on query caching: query-caching-and-scheduling ## When are data snapshots created? ### If static caching is enabled A data snapshot is created when: • A new version is saved • Refresh all results is selected ### If scheduled runs are enabled A data snapshot is created when: • Your queries are executed due to the run schedule • Refresh all results is selected --- # Build Trusted Context Manage the skills, context and definitions across your organization. ## Agent Context URL: https://learn.count.co/build-trusted-context/agent-context Set context at the workspace, connection and project level, so agents always have the right business logic. Count's agents combine context from several sources to answer your questions well. Setting it up properly means agents give consistent, checkable answers without you repeating yourself in every prompt. ### Where context lives Context is organized in a hierarchy: workspace, connection, and project. Each level is owned by different people and changes at a different pace, so where you put a rule matters as much as how you write it. ### What context controls Context can cover tone and brand, business definitions, access and governance, and output preferences from brand formatting and style, through to which fields to use for a given metric, what an agent is and isn't allowed to touch, and how it should label its own work. ### What makes good context Before rolling a piece of context out more widely, check it against a few questions: - Actionable? Does this actually change what the agent does? You can test this within a query in side-by-side agents in the canvas. - Unambiguous? Could two reasonable people interpret this differently? - Current? Is this still true and verifiable? - Scoped correctly? Would this be more effective and useful at a different level of the context? - Minimal? Is there a shorter, more concise articulation that doesn't sacrifice clarity? - Testable? Can you prove a positive improvement in side-by-side testing? ### Examples - Workspace "All financial figures are reported in GBP, and our fiscal year runs from April to March." - Connection "In the Snowflake warehouse, use dim_customer.customer_id for all customer joins, not raw_customers.id." - Project "For this campaign analysis, a bounce is any session under 5 seconds, not the default 30-second definition." ### Building & maintaining context There are two ways to create or update context: - In Count directly fastest for anything you'll only set once or twice. - Via the API sync it automatically whenever it needs to update from your own systems. Before rolling a rule out at the workspace or project level, context can be tested in a canvas. Refine it there until the agent responds the way you want, then promote it up. ### Workspace Context URL: https://learn.count.co/build-trusted-context/agent-context/workspace-context Create and manage workspace context for organization wide branding guidelines, definitions and rules. Workspace context applies everywhere: to every project, connection, and canvas. It's owned by workspace owners and business leaders, and typically changes quarterly or less, since it holds the standing rules the rest of the business is meant to build on. Workspace context can be defined via the UI in the workspace settings under the AI tab. or synced via the API if it needs to update automatically from your own systems: ### What belongs in workspace context? Workspace context typically falls into a few categories: - Tone & identity house style and formatting conventions agents should follow without being asked, like currency, date format, and brand colours. - Business foundations foundational facts about how the business runs, like billing model and fiscal calendar, that every team should already agree on. - Data governance rules about disclosure and care, like flagging AI-generated output or asking for validation before it's used. ### Connection Context URL: https://learn.count.co/build-trusted-context/agent-context/connection-context Create and manage connection context for data source specific guidelines, definitions and rules. Connection context attaches to a specific data source whether that's a database, business application or a Count Metrics catalog. The context applies wherever that connection is used, regardless of which project references it. Connection context can be defined via the UI in any given connection under 'Manage connection'. or synced via the API if it needs to update automatically from your own systems: ### What belongs in connection context? Connection context might include: - Data quirks: known issues or exceptions in the underlying data that agents need to work around, like a table that double-counts certain records before a given date. - Definitions & naming: which field to use when a metric could be calculated more than one way, or how a column name maps to what it actually means. - Governance & sensitivity: what shouldn't be surfaced, or needs extra care. ### Project Context URL: https://learn.count.co/build-trusted-context/agent-context/project-context Create and manage project context for guidelines, definitions and rules specific to a team, department or use case. Project context is scoped to a single project, and changes on an ongoing basis as the team or work evolves. Where workspace and connection context set the ground rules everyone builds on, project context is for the things that only make sense for a particular team, department, or piece of work. Project context can be defined via the UI in any given project under 'Manage project'. or synced via the API if it needs to update automatically from your own systems: ### What belongs in project context? Connection context might include: - Scope & definitions: what this project covers, and how term sshould be interpreted here even if they mean something different elsewhere in the business. - Data guides: team-specific direction on how to work with data within this project: which source is authoritative for this team's questions, which fields to prioritize, caveats that only apply to how this team uses the data. - Formatting & output: team-specific style guides: preferred chart types, layouts and naming conventions for this project's outputs. ### Managing Agent Context via API URL: https://learn.count.co/build-trusted-context/agent-context/managing-agent-context-via-api Example workflow for updating and maintaining Count context via API Count's AI agent follows instructions outlined in agent context, which can be set at the workspace, project, or connection level. Context can be manually edited in the Count UI. But it's also exposed through Count's API (GET/PATCH on workspace, project, and connection resources), which means it can be read and written programmatically, just like any other piece of config. API examples Below are some example Python scripts for interacting with the agent context via API. More API code examples including cURL and Typescript versions of the below can be found in the API reference under the API+MCP tab in your workspace settings. Workspace context Get workspace context Patch workspace context Project context GET project context PATCH project context Connection context GET Connection context PATCH Connection context ### Why use the API to maintain context? Treating agent context as a file instead of a UI field gets you everything tools like Git and GitHub already give you for code: - History and blame: every change to an agent's instructions is a commit, with an author and a reason, rather than a silent overwrite. - Review before it goes live: a change to the agent's instructions can go through a pull request, with a diff, before it affects anything. - A single source of truth: the repo is authoritative, so there's no drift between "what's live" and "what someone remembers editing in the UI." - Rollback: reverting a bad context change is a simple revert rather than a rebuild. - Use it elsewhere: managing context centrally allows you to use the same context across your agentic stack. ### An example approach This is the pattern we put together in count-context-sync-toolkit, and it's deliberately simple: - Each destination (a workspace, project, or connection) gets one markdown file in the repo. The file's content is the context: what you write is what gets pushed. - A small script compares each file against what's currently live via the API. - It can be run in 'check' mode to identify differences between repo hosted context files and live Count context prior to merging. - On merge, it can be run to push any file that differs, overwriting live context in Count. - Two GitHub Actions wire this into normal Git workflow: - one comments a preview diff on pull requests that touch context files, - and one pushes automatically once those changes are merged to main. ## Count Metrics URL: https://learn.count.co/build-trusted-context/count-metrics Create a governed data model using our powerful semantic layer. Count Metrics is Count’s semantic layer, providing a trusted source for your data logic, from business metrics to complex SQL and repetitive joins, by defining them once. Consistently and centrally. ## Concepts The semantic layer consists of four types of entity: catalogs, datasets, views and catalog maintainers. Views — Selections of fields (measures and dimensions), along with assorted metadata. Views can be quickly initialised from database tables and canvas cells, and can be executed on remote databases, as well as in DuckDB and Python local to the user. Datasets — A collection of views and the information about the relationships between them. These make up the tables that users see when constructing queries from the semantic layer. Catalogs — the highest-level object within a semantic layer. Catalogs are self-contained entities that house various views and datasets, and can be used as project data sources (just like database connections). Each catalog is stored in a separate Git repository. Catalog config file — The catalog config file (count_catalog.yml) allows you to apply catalog wide settings. Currently this supports caching & scheduling. Caching can be optionally configured. It makes queries faster by keeping local copies of your tables on our servers. When a view is executed, the system copies the table and runs a query for that view. Exploring the catalog then uses these copies for quicker results. AI context via AGENTS.md — AI agents interacting with a catalog can also read an AGENTS.md file in the catalog repository. This allows you to provide additional structured context, guidance, conventions, or business definitions that may not live directly in views or datasets. Read more about about agent context best practice here. ### Setting Up A Catalog URL: https://learn.count.co/build-trusted-context/count-metrics/building-a-catalog The Count Metric semantic layer is represented as one or more catalogs. The catalog is the foundation of your semantic layer. It stores all your views and datasets. You can get a catalog created in just a few minutes. This guide walks you through creating and managing a catalog step by step. ## Creating a catalog Click on Create new catalog in the sidebar of the workspace UI. You'll be prompted first to connect to Github, Select the data source(s) you want to be available in your catalog. You'll be prompted to optionally connect to Github. (Read more about the Github integration here). Choose specific tables from your source to appear in your catalog as views (optional). These views can be edited or extended later. Invite your team to the catalog and assign roles. If you chose to create your catalog from database tables, you can now Validate and commit the new views. ⚠️ At this point, no one can access the catalog unless: • You grant them access, or • You assign the catalog to a project they are a member of. ## Troubleshoot I can't see a create new catalog button in my workspace You may not have the right access to create catalogs in your workspace. You need to be a workspace Admin or Owner to create catalogs. I can't see the data connection I want to use in my catalog You may not have the right access to add the data connection to your catalog. You need to be an Admin of the data connection to be able to add it to projects or catalogs. The data connection may not exist, in which case you need to create it. I can't find the tables I want to add to my catalog in the create from database tables dialog You may need to refresh the database schema to bring the latest list of tables on your database connection into our UI. The tables might not exist on your database connection, or in some cases the tables exist in a different schema to main schema connected. In this case you can still access those tables, and still create catalog views on them, but not using our create view from table dialog. I can't find the workspace member that I want to add to my catalog The user likely doesn't exist on your workspace. I can't update the access role on my catalog member(s) The roles users can have on the catalog are limited by their workspace role. Workspace owners and admins can take on all catalog roles, analysts and viewers have a limited set of roles. The data connection I want to use in my catalog is greyed out You need to upgrade your access on the database connection to Admin. I can't find the project I want to add my catalog to You may not have access to the project. Either upgrade your project access to Admin or add an existing project admin to the catalog as an Admin. It could also be that the project doesn't exist. The project I want to add my catalog to is greyed out While you have access to view the project, you don't have access to add the catalog to the project. Either upgrade your project access to Admin or add an existing project admin to the catalog as an Admin. #### Count Metrics x Github URL: https://learn.count.co/build-trusted-context/count-metrics/building-a-catalog/count-metrics-with-github Manage catalogs centrally with our Github integration Connect your Catalog to GitHub to manage your semantic layer definitions centrally. This integration enables version control workflows and keeps your data transformation logic and metrics definitions in sync. ## Why use GitHub with Count Metrics? The GitHub integration is designed for teams who want to: - Colocate catalog files with dbt projects - Keep your semantic layer definitions close to your transformation logic - Enable version control workflows - Use branches, pull requests, and code reviews to manage changes to your metrics definitions - Collaborate across tools - Edit catalog files in Count's UI or directly in your GitHub repository - Maintain consistency - Sync changes bidirectionally between Count and GitHub automatically ## Getting started ### Connecting an existing catalog to GitHub - Navigate to your catalog settings - Click Connect to GitHub - Select the GitHub repository where you want to store your catalog files - If you have existing catalog files, add them to the repository first (you can download your files directly from the catalog editor) ⚠️ Important: Count will warn you if the catalog files in your GitHub repository don't match your existing catalog configuration. Make sure to sync these before proceeding. ### Creating a new catalog with GitHub When creating a new catalog, you’ll see an option to connect it to a GitHub repository from the start. For a given Github repo, we recommend only having a single catalog. This is because all the dataset and view files in a repo will be synced to the catalogs they're connected to. If you don't want users of the catalog to have access to the whole catalog, it's possible to only share specific datasets with projects (see here). ## Working with branches Count Metrics supports branch-based workflows to help you develop and test changes before merging them to production. ### What's supported in Count - Creating branches - Create new branches directly in the Count UI - Deleting branches - Remove branches you no longer need - Committing changes - Commit changes to any branch from Count - Viewing changes - See what's changed before committing ### What happens in GitHub - Merging branches - Merge branches using pull requests in GitHub - Updating from main - Pull the latest changes from your main branch in GitHub - Protected branches - Count respects GitHub's branch protection rules and will prevent commits to protected branches ## Pull request checks When you open a pull request in GitHub that includes catalog file changes, Count automatically adds: - Status checks - Validation results showing whether your catalog changes are valid - PR comments - Detailed information about what's changed, including links back to Count for easy review This helps your team catch issues before merging changes to production. ## Editing files The Count catalog editor gives you access to all files in your connected repository, not just catalog files. This means you can: - View any file in the repository - Edit catalog-related files directly in Count - Switch between Count's UI and your code editor as needed ## Troubleshooting GitHub app permissions error If your organization installed the Count GitHub app before Nov 25, you may need to approve updated permissions. Go to your organisation home page in Github, click the Settings tab, then go down the “Github Apps” in the sidebar. You'll see the “count.co” app there with a button to review the request. Protected branch errors If you see an error when trying to commit in Count, check whether the branch is protected in GitHub. You'll need to commit changes through a pull request workflow instead. #### Editing A Catalog URL: https://learn.count.co/build-trusted-context/count-metrics/building-a-catalog/editing-a-catalog Editing A Catalog From the catalog’s main page, you can see all of the key information about your catalog at a glance, including its description, members, data sources, and views. Each area of the page provides entry points to manage different aspects of the catalog. ## Updating the About section Update the catalog description, name or sharing permissions; Delete the catalog or set up Count secrets in the About section of the catalog's main page. Clicking on Manage catalog allows you to change your catalog name, disable sharing, define Count secrets or delete your catalog. - Name - Rename your catalog. This updates how the catalog appears across projects and canvases. - Allow sharing - Enable or disable sharing of the catalog and its canvases. - Agent context (Catalog-level) - Provide context that will be available to the AI agent when working with this catalog. This context is combined with workspace-level and project-level context. Read more about context best practice here. - Secrets - Define secrets that can be used in Python cells for secure network requests. - External source - Connect a GitHub repository as the external source for the catalog. - Delete - Permanently delete the catalog, this action cannot be undone. ## Managing Members Add or remove workspace users to the catalog by clicking on Manage access. To add new members to the catalog, click Add members. Adjust access roles by using the dropdown next to each member. Use the search bar to find or filter existing members for easier management. ✅ Note: You don’t need to be a catalog member to access its data, as long as the catalog is assigned to a project you belong to. Catalog members are those who should be able to view, edit, or contribute to the catalog’s configuration. ## Managing Data Click on Manage data to add new data sources or remove existing ones. Adding new data sources is as easy as toggling the switch next to them in the Manage data dialog. You will be able to add all data sources that you have access to as a workspace member. If you can't see the data connection that you want to make available to the catalog, you either don't have access to add it to projects/catalogs or the connection doesn't exist. ## Managing Projects Adding a project to your catalog allows project members to use the catalog in their canvases or in explore mode on that project. Clicking Manage projects allows you to add or remove projects. You can add or remove a project by toggling the switch next to it in the Manage projects dialog. You can then set which dataset(s) you'd like the given project to have access to. If you can't see the project you want to add or if it's greyed out, then you might not have the correct access rights on that project or the project might not exist. #### Catalog Configuration File URL: https://learn.count.co/build-trusted-context/count-metrics/building-a-catalog/catalog-config Catalog configuration file The catalog configuration file (count_catalog.yml) allows you to apply catalog-wide settings. Currently this supports caching & scheduling. Caching can be optionally configured. All new catalogs created will have this file pre-filled by default. Existing catalog will now see this file, but it will be empty and will need populating. Caching applied in the catalog maintainer file will be overruled by any view level caching settings applied. Leave the view level caching settings empty if you'd like them to default to the catalog maintainer settings. ## The Schema ## Example YAML The default catalog maintainer file has the following YAML, which can be configured to your preferences. ### Views URL: https://learn.count.co/build-trusted-context/count-metrics/views Catalogs are constructed of Views that represent your tabular data. Views are a collection of fields (measures and dimensions) along with metadata, providing a flexible and efficient way to organize and manage your data. Views can be initialized quickly from database tables or canvas cells. Each view is stored in a separate YAML file, ensuring clarity and ease of customization. ## View YAML schema Views and datasets are build on YAML files. The schema for view definitions is displayed next to the YAML editor in Count. Here is an example of the YAML schema. Example view YAML See the subpage on Customizing views to learn more. ## Building Views There are two ways to create Views in Count Metrics: 1. From database tables – The fastest and most straightforward method, ideal for well-structured datasets. 2. From canvas cells – A flexible option that allows for multi-database joins and pre-processing within Count. #### Creating Views From Database Tables URL: https://learn.count.co/build-trusted-context/count-metrics/views/creating-views-from-database-tables Generate views from database tables with a single click If your data is already well-structured, this is the quickest way to create a View. To get started: Navigate to the catalog YAML editor by clicking Edit catalog on the catalog main page Click on the + button, and then either select Create view (if you want to manually create a single view) or Generate files from tables. If you choose to generate files from tables and select your tables, Count will automatically create views and datasets for the tables you select. Click on the Source Control tab, and then Validate and commit to publish the new files. The view’s YAML file will be automatically populated with fields from the table, which you can then customize, remove, or edit as needed. ## Auto-generated view YAML The view YAML are entirely customizable and can be edited directly in the catalog YAML editor. For a full overview of how to customize view YAML, see the following pages. Each auto-generated view YAML file leads with a descriptive comment identifying the view as auto-generated and the name of the schema object it is generated from. Example auto generated YAML Auto-generated views are a one-to-one extract of the underlying table. To add filters, joins or additional SQL logic such as case statements, edit the query in source All fields will be given a user friendly label and, if it exists on the data connection schema, a description. Numeric fields have a predefined list of default aggregates Date fields have a predefined list of default timeframes. #### Creating Views From Canvas Cells URL: https://learn.count.co/build-trusted-context/count-metrics/views/creating-views-from-canvas-cells Your canvas creations can effortlessly become views For more complex data modeling or combining multiple databases, you can create Views directly from a canvas cell. ⚠️ You can only do this from catalog canvases. From the catalog homepage click on New canvas. Perform your data modelling within it using SQL cells. You generate views from single cells, but any upstream references are automatically included as dependencies. Once you're satisfied with the results, select the cell that contains the data you want to use. Scroll down the right sidebar and click Export view. This will generate a new view in the catalog editor, pre-filled with the fields from the selected cell. Go to the Source Control tab and click on Validate and commit to publish the new view. ## Canvas cell view YAML Just like auto-generated views the YAML file is entirely customizable and can be edited directly in the catalog YAML editor. There is no generated header comment in views created from canvas cells. The name matches the cell name by default. Example YAML - The source query is identical to the query in the cell you generated the view from. - Views generated from catalog canvas cells contain a url link to the canvas they were created in. - If your cell references other cells in the canvas they will appear as dependencies. It is even possible to join data from multiple data connections in a single view. - Views generated from catalog canvas cells define only the field names and datatypes. This is the minimum requirement for functionality and can be customized to include labels, descriptions, expressions, aggregates or timeframes. #### Customizing Views URL: https://learn.count.co/build-trusted-context/count-metrics/views/customizing-views Encode your data's representation in views. Views provide a structured way to organize and manage data, but they are also highly customizable. Within the Catalog Builder, the Schema on the right-hand side offers a range of options to edit and refine your View YAML. These customizations allow you to improve usability, enhance data clarity, and provide stakeholders with flexible analysis options—all without writing additional SQL. ## Schema The schema displays a list of available customization options you can use in the view YAML file. We've broken these down into: - Descriptive fields - Source configuration - Caching - Fields and field formatting - Joins with other views ### Descriptive fields ### Extend field ### Source configuration ### Caching ### Fields formatting See here for details and examples related to the fields property. ### Joins with other views #### View Fields URL: https://learn.count.co/build-trusted-context/count-metrics/views/view-fields Configuring fields for catalog views Catalog views have fields to expose the underlying data. Below is the schema which details the different options for configuring the fields for views and some examples to get you started. ## Fields Schema ## Example uses ### Using expression, type and aggregates Custom calculated fields look no different to predefined fields in the canvas UI. ### Using timeframes Here’s how this looks in the canvas. ### Using description In the canvas UI, descriptions appear in tooltips when you hover over the field with your cursor. ### Using group In the canvas UI, field groups will appear as expandable sections that reveal their fields when clicked. ### Datasets URL: https://learn.count.co/build-trusted-context/count-metrics/datasets Datasets define the relationships between your views and their metrics. ## Organize views and define relationships A dataset is a collection of views and the relationships between them, defining the structured tables that users interact with when querying data from the catalog in the canvas. Datasets should be designed to serve a business objective or function. This approach ensures that datasets are meaningful, actionable, and aligned with business needs. Each dataset is stored in a separate YAML file and can be built using one or more views. There are two ways to specify the views for a dataset: - using from and join to define the joins in the dataset; or - using views which requires that the joins are defined in the views. Regardless of where they are defined, the joins must be given join types (e.g., one-to-many, many-to-one) to ensure correct aggregation and maintain symmetrical data aggregation. Once configured, datasets automatically generate SQL based on predefined logic, enabling accurate and consistent data exploration within the canvas. Datasets are listed in the Datasets section of the catalog YAML editor. They can also be seen in the catalog homepage. ## Dataset YAML schema Example dataset YAML See the customizing datasets page to learn about how to customise the dataset YAML. #### Creating Datasets URL: https://learn.count.co/build-trusted-context/count-metrics/datasets/creating-datasets Creating your first Count Metrics dataset. Datasets can either be auto-generated as part of the 'generate view from table' workflow, or they can be created from scratch in the catalog YAML editor. ## Creating a dataset To create a dataset open the catalog YAML editor by clicking on Edit catalog Click the + next to the search bar. A new dataset starts as a blank template, and you’ll need to define its views, joins, and attributes before it becomes functional. You can rename your dataset file in the Datasets file directory by double clicking on the file. By default its name will be 'Untitled' ## Auto-generated Dataset YAML If you generate views directly from tables, datasets are created for you automatically. Each auto-generated dataset YAML leads with a descriptive comment identifying it as auto-generated, the name of dataset is, by default, the same as the name of the base view of the dataset. A user friendly label is generated, this will be how the dataset appears to users in their projects. A dataset can reference one or more views. The from attribute contains the base view of the dataset, in SQL this is the first view in the from clause. Datasets containing only one view will only have the from attribute. When multiple views share fields with the same name and datatype, they are combined into a single dataset with default joins on those fields. Otherwise, one dataset is created per view. Each additional view in the dataset is referenced in the join group. For each join view contains the name of the view to be joined, constraint the join condition, and relationship the relationship cardinality between the base view and the joined view. The schema displays a list of available options you can use in the dataset YAML file. Learn more on the customizing datasets page. #### Customizing Datasets URL: https://learn.count.co/build-trusted-context/count-metrics/datasets/customizing-datasets Expose and join your views through datasets. Datasets are a collection of views and the information about the relationships between them. These make up the tables that users see when constructing queries from the semantic layer. ## Schema The schema displays a list of available customization options you can use in the dataset YAML file. ## Example uses ### A full YAML example ### Using name, description and label - Choose a system name and a user friendly label for your dataset. The system name must be unique among the datasets of this catalog. - You have more freedom in your choice of label, but keep in mind that datasets with similar or the same label may be confusing for your catalog users. - Dataset descriptions will appear in the catalog homepage. ### Using join - relationship contains the cardinality of the relationship between the views being joined. - Join type can be any one of: left, right, inner, or full - Defining multiple joins in a dataset is as simple as adding an additional view to the join list. ### Save Changes To The Catalog URL: https://learn.count.co/build-trusted-context/count-metrics/save-changes-to-the-catalog Iterate your catalog in a version controlled environment. After building and customizing your views and datasets in the catalog, it's essential to commit changes to ensure everything is up-to-date. Committing changes makes sure your updates are reflected in the catalog and available for use in the canvas. Use the Source Control tab to manage versions and branches. Changes are flagged with M for modified objects, A for added objects, D for deleted objects and R for renamed objects. ## Ensuring data integrity in catalog changes Maintaining accurate, reliable data is essential for effective decision-making. Count Metrics incorporates features that detect errors before they impact reports and provide a clear history of changes, ensuring data consistency and integrity across projects. - Validation checker - Version control & Branches #### Catalog Validation URL: https://learn.count.co/build-trusted-context/count-metrics/save-changes-to-the-catalog/catalog-validation Iterate your catalog safely with pre-commit validation. Count Metric's Validation Checker proactively identifies issues in reports before catalog changes are committed, ensuring that errors are flagged early and preventing faulty data from reaching users. By catching problems at the source, it helps maintain report accuracy, consistency, and reliability, reducing the need for last-minute fixes and building trust in the data. When a change is committed, Count checks all connected cells for errors both before and after the update. The results are categorized into three types: • New - cells that will break as a result of the change. • Existing - cells that were already broken and remain broken. • Fixed - cells that were previously broken but are now resolved. While the validation checker catches most issues, some errors, such as missing database tables, unavailable databases, or runtime issues (e.g., division by zero), can only be detected when queries are executed. All errors across all canvases are reported, even those outside the user’s access. To assist with collaboration, a list of contributors for each affected canvas is provided ### See changes from Source control ### Breaking change error message #### Catalog version Control & Branches URL: https://learn.count.co/build-trusted-context/count-metrics/save-changes-to-the-catalog/catalog-version-control Store your catalog definition in a version controlled environment. With Version Control in Count Metrics, you can easily track and manage changes made to your catalog. The commit history feature provides a log of all previous changes, allowing you to view the changes made at any point in time. By selecting the commit history icon, you can access a detailed history of updates made to the catalog and have the option to revert to a previous version if necessary. ## Branches To make it easier to develop catalogs while they are in production with users users, you can create branches from any working branch, commit, and then finally merge back ultimately to main . Once in a canvas, you can preview and test your branch catalog by selecting it in the dataset pane. This will update the data source of any cell referencing that catalog to reflect the commited changes within the branch. ## Benefits of version control - Track changes - view a history of all catalog changes, making it easy to understand updates over time. - Revert to previous versions - quickly roll back to a prior version if a change causes issues. - Maintain data integrity - safeguard against accidental changes and ensure stable, reliable data. - Enhanced collaboration - easily see who made changes, improving team communication and workflow. ### Extending catalog files URL: https://learn.count.co/build-trusted-context/count-metrics/extending-catalog-files Extending view/dataset files allows you to reuse shared configuration for multiple views/datasets without needing to duplicate this configuration. Count catalog files (views and datasets) can extend other files using the extends property. Both Count YAML files and third-party catalog files (e.g. LookML and Snowflake files) can be extended. Extending view/dataset files allows you to reuse shared configuration for multiple views/datasets without needing to duplicate this configuration. For example, you might have a single database table (e.g. users) which makes sense to expose as two different views for the two different ways that it is joined with other tables (e.g. customers in the context of the orders table or reviewers in the context of the reviews table). In this case, you may have a users view which isn't actually used in any datasets and two views that extend this users view: customers and reviewers (reusing the source and many of the fields). Maybe only the view names, label, and description are overwritten or maybe some fields are omitted, given new labels/descriptions, or additional fields are added. ### Extending a View ### Extending a Dataset ### How Extension Works - Properties from the base file are merged into the extending file. The extending file's properties take priority. - Arrays (fields, joins) are merged by identifier (name for fields, view for joins). Items present in both files use the extending file's values, with gaps filled from the base. - Extension chains are supported (A extends B extends C). - The omit_fields, omit_joins (for views) and omit_views, omit_joins (for datasets) options allow selectively excluding items inherited from the base. - For example while extending a view, it's possible to add additional fields, omit fields from the base view, and override field properties (e.g. the label or expression of the field). ### Extendable File Types - .view.yml files can extend: - First-party Count views (.view.yml) - Views generated from LookML view files (.view.lkml) - Views generated from Snowflake YAML files - Views generated from OSI YAML files - .dataset.yml files can extend: - First-party Count datasets (.dataset.yml) - Datasets generated from LookML explore or model files (.explore.lkml and .model.lkml) - Datasets generated from Snowflake YAML files - Datasets generated from OSI YAML files See here for more details about extending views/datasets generated from third-party files. ### Third-party file support URL: https://learn.count.co/build-trusted-context/count-metrics/third-party-file-support Use or import third-party files, such as LookML or Snowflake Semantic Views, in Count Metrics. Count supports importing and on-the-fly conversion of third-party files into Count catalog views and datasets. Currently this includes: - LookML files - Snowflake YAML files - OSI (Open Semantic Interchange) files The third-party support allows teams to maintain their semantic layer in these products but still use them in Count or to migrate from these products to Count and not have to start from scratch. Not all features of these third-party files are supported. See the specific details of each file type for limitations. ## Overview There are two separate ways that third-party support is offered for Count Metrics: - Automatic conversion - third-party files in the catalog repo are converted on-the-fly into Count views and datasets. - Manual conversion - A one-time import that produces first-party Count YAML files from third-party files, either by uploading a third-party project or converting third-party files that are already present in the repo. Additionally, Count catalog files can extend third-party files (or other Count files), inheriting their fields and properties while allowing overrides and omissions. ## Automatic Conversion When third-party files (e.g. snowflake.yaml, .view.lkml, .model.lkml, .explore.lkml) are present in a catalog repo, either uploaded directly or included from a connected GitHub repository, they can be automatically converted into Count views and datasets. Whenever these files change, the generated Count files are automatically updated to reflect the latest third-party definitions. This allows teams to maintain their third-party semantic layer files as the source of truth while using Count for exploration and modeling. Automatic conversion is controlled via the count_catalog.yml config file: New catalogs will be initialised with automatic conversion already enabled with a config file like this: ### How It Works - LookML: - .view.lkml files are converted to Count views (.view.yml) - .model.lkml and .explore.lkml files are converted to Count datasets (.dataset.yml) - view refinements (views whose names start with "+") are merged with their base view automatically - Snowflake: - Each table in a YAML file is converted into a Count view - Each YAML file is converted into a Count dataset - OSI: - Each dataset in a semantic model is converted into a Count view - Each semantic model is converted to a Count dataset - Converted files are generated on the fly and appear in the catalog editor as read-only generated files, tagged with their source. - If a first-party Count file exists with the same name as a generated file, the first-party file takes priority and the generated file is marked as "Overridden". ### Include/Exclude Patterns The include and exclude arrays accept glob patterns matched against file paths in the repo: - If `include` is specified, only files matching at least one include pattern are converted. - If `exclude` is specified, files matching any exclude pattern are skipped, even if they match an include pattern. - If neither is specified, all third-party files are converted. ## Manual Conversion Manual conversion produces first-party Count YAML files from uploaded third-party files. Unlike automatic conversion, the resulting files are regular catalog files that you maintain and can edit directly. It should be noted that manual conversion (unlike automatic conversion) does not keep the Count files in sync: if the original third-party files change, the manually converted Count files will not update automatically. This approach is best for teams who want to migrate their third-party definitions into Count and then maintain them directly in Count going forward. ### Import third-party files Upload a collection of third-party files through the catalog editor's "Import third-party files" actions. This parses the uploaded files, converts them, and presents a selection UI where you can choose which views and datasets to create. ### Convert Existing Files If third-party files are already present in the repo (e.g. from a connected GitHub repository), use the "Convert ... files" action in the catalog editor to convert them into first-party Count files. A modal allows you to review and select which files to convert. When files are manually converted, automatic conversion is disabled for those files to prevent duplicates (it can however be re-enabled if needed by editing the count_catalog.yml configuration). ## Extending Files Count catalog files can extend other files using the extends property. Files that can be extended include both third-party files and first-party Count YAML files. See here for more information about extending Count YAML files. Extending third-party files allows you to reuse and customize third-party definitions without modifying the original third-party files. For LookML specifically, while views without a data source (i.e. no sql_table_name or derived_table) can't be converted as they are, they can still be extended in this way. ### Extending a View ### Extending a Dataset #### LookML support URL: https://learn.count.co/build-trusted-context/count-metrics/third-party-file-support/lookml-support Use or import LookML files in Count Metrics. Count supports importing and on-the-fly conversion of LookML files into Count catalog views and datasets. This allows teams migrating from Looker, or maintaining a LookML-based semantic layer alongside Count, to reuse their existing LookML definitions. Not all LookML features are supported. See Limitations for details. ## General support LookML files are just one type of third-party file that Count Metrics supports. This support includes: - on-the-fly (or automatic) conversion for teams who want to continue maintaining their semantic layer definitions outside of Count; - once-off (or manual) conversion for teams who want to fully migrate their existing semantic layer definitions into Count; and - extending automatically converted views and definitions to adjust them without needing to change the third-party files. See here for more details on how Count Metrics supports third-party files generally. This page will focus just on the specific details of this related to LookML files. ## LookML Conversion Details ### What Is Converted - LookML view with sql_table_name -> Count view with table source - LookML view with derived_table.sql -> Count view with query source - LookML dimension -> Count field (no aggregate) - LookML dimension group (type: time) -> Count field with timeframes - LookML measure -> Field with aggregate - LookML explore -> Count dataset - LookML view refinements (+view_name) -> Merged with base view - LookML view extends -> Separate view extending base view - LookML case blocks -> SQL CASE WHEN expressions in fields - LookML tier/bin types -> SQL CASE WHEN expressions in fields - LookML measure with filters -> Aggregate `CASE WHEN` expressions - LookML manifest constants (@{name}) -> Resolved inline - LookML ${TABLE}.column references -> Resolved to column - LookML ${field_name} references -> Resolved to field expressions ### Supported Types string, number, integer, boolean, yesno (converted to boolean), date, time (converted to date). ### Supported Aggregation Types count, count_distinct, sum, sum_distinct (converted to sum), avg, average (converted to avg), average_distinct (converted to avg), median, mode, max, min, stddev_pop, stddev_samp, var_pop, var_samp. ### Supported Timeframes raw, date, year, quarter, quarter_of_year, month, month_num, month_name, week, day_of_year, day_of_month, day_of_week, hour, minute, second, and their _trunc variants. ### SQL Rewrites The converter applies several SQL transformations to ensure compatibility: - CURRENT_DATE() / CURRENT_TIMESTAMP() → today() / now() - DATE_DIFF(...) / DATEDIFF(...) (BigQuery and Snowflake variants) → date_sub(...) - CAST(... AS INT64) → CAST(... AS INTEGER) ### Format Conversion Common LookML value formats are mapped to Count format specifications, including currency formats (usd, gbp, eur, etc.), percentage formats, and decimal precision formats. ## Limitations Count supports a broad subset of LookML. However, certain LookML features do not have direct equivalents in Count. During conversion: - Unsupported views, datasets, or fields are skipped. - The skipped definitions are included as commented sections in the generated files. - An explanation is provided inline to indicate why the conversion was not possible. This ensures that no definitions are silently dropped and that any required manual adjustments are visible. Below are the current known limitations when converting LookML to Count. ### Parameters and Liquid Templating LookML parameter definitions (`parameter`) and Liquid template expressions ({% ... %}, {{ _filters['...'] }}) are not supported. Fields that rely on parameters or Liquid templating will be commented out in the converted output with an explanation. ### Cross-View Field References Referencing fields from other views in field expressions (e.g. ${other_view.field_name}) is not supported. Only references to fields within the same view (${field_name}) and the table reference (${TABLE}.column) are resolved. ### Drill Fields and Sets LookML set definitions and drill_fields are not converted. These are skipped during conversion as Count does not have an equivalent concept. ### Field Expression SQL Field expressions can only use a limited SQL dialect that Count uses in various places such as visuals and low-code cells (see here). Complex SQL constructs, warehouse-specific functions, or deeply nested subqueries may not convert successfully. Fields with unsupported expressions are commented out with a note explaining the issue. ### Views Without Data Sources LookML views that have no sql_table_name or derived_table (i.e. views intended to be used only via extends) produce views without a source. These views cannot be used directly in Count but can be extended by Count catalog files that provide their own source. ### Other Unsupported LookML Features - Relative date filters (sql_always_where with Liquid date filters) - User attribute references (_user_attributes) - html property on fields - link property on fields - order_by_field - Custom value_format strings (common named formats are supported) - Some join types may not have direct equivalents #### Snowflake support URL: https://learn.count.co/build-trusted-context/count-metrics/third-party-file-support/snowflake-support Use or import Snowflake YAML files in Count Metrics. Count supports importing and on-the-fly conversion of Snowflake YAML files into Count catalog views and datasets. This allows teams migrating from Snowflake, or maintaining a Snowflake-based semantic layer alongside Count, to reuse their existing Snowflake definitions. Not all Snowflake features are supported. See Limitations for details. ## General support Snowflake YAML files are just one type of third-party file that Count Metrics supports. This support includes: - on-the-fly (or automatic) conversion for teams who want to continue maintaining their semantic layer definitions outside of Count; - once-off (or manual) conversion for teams who want to fully migrate their existing semantic layer definitions into Count; and - extending automatically converted views and definitions to adjust them without needing to change the third-party files. See here for more details on how Count Metrics supports third-party files generally. This page will focus just on the specific details of this related to Snowflake YAML files. ## Snowflake Conversion Details Count supports two Snowflake YAML specifications: - Semantic View YAML files: YAML files used to generate native Snowflake schema objects. Use measures for row-level measures. Relationship types are auto-inferred rather than explicitly declared. Adds access_modifier support on fields and metrics. - Semantic Model YAML files (legacy): YAML files stored on a Snowflake stage, used with Cortex Analyst. Uses facts for row-level measures (equivalent to measures). Supports explicit join_type and relationship_type on relationships. See the Snowflake documentation for the full specification. Both specs share the same underlying structure and are converted using the same process. Differences are handled transparently - for example, measures and facts are treated identically. ### What Is Converted - Snowflake semantic model or semantic view -> Count dataset - Snowflake table with base_table -> Count view with table source - Snowflake dimension -> Count field (no aggregate) - Snowflake time dimension -> Count field with timeframes - Snowflake fact / measure -> Count field, with aggregate if default_aggregation is set - Snowflake metric -> Count field with aggregate (parsed from expression) - Snowflake metric with filter -> Aggregate CASE WHEN expression - Snowflake model-level metric (single-table reference) -> Field on the referenced view (see Model-Level Metrics) - Snowflake relationship -> Count join - Snowflake foreign_keys / unique_keys -> Inferred joins (when no explicit relationship covers the same table pair) - Snowflake primary_key -> Primary key fields on view ### Supported Types - varchar, nvarchar, char, nchar, character, text, string -> converted to string - number, decimal, numeric, fixed -> converted to integer or number depending on the scale - int, integer, bigint, smallint, tinyint, byteint -> converted to integer - float, double, real, double precision, float4, float8 -> converted to number - boolean -> converted to boolean - date, datetime, timestamp -> converted to date - time -> converted to string (no time type in Count Metrics) ### Unsupported Types variant, array, object, binary, varbinary, geography, geometry. Fields with unsupported types are commented out in the converted output with an explanation. ### Supported Aggregation Types count, count_distinct, sum, sum_distinct (converted to sum), avg, average (converted to avg), average_distinct (converted to avg), median, mode, max, min, stddev_pop, stddev_samp, var_pop, var_samp. ### Supported Timeframes Time dimensions are converted with the following timeframes: year_trunc, quarter_trunc, month_trunc, week_trunc, day_trunc, hour_trunc, day_of_week, and the raw (untruncated) value. ### Relationships and Joins Snowflake relationships are converted to Count joins. The converter supports: - Explicit relationships defined at the model level with relationship_columns or expr - Implicit relationships inferred from foreign_keys on tables (when no explicit relationship already covers the same table pair) - relationship_type mapping: one_to_one, one_to_many, many_to_one, many_to_many - join_type mapping: inner, left / left_outer (default), right / right_outer, full / full_outer - For foreign key–derived joins, the relationship type is inferred based on whether the foreign key column(s) are declared as unique keys on the source table ### Model-Level Metrics Metrics defined at the semantic model level (outside of any table) are distributed to table views by analyzing tableName.fieldName references in the metric expression: - Single-table reference: assigned to that table's view as a normal metric field - Multi-table reference: assigned to the first referenced table's view but commented out (cross-view metric expressions are not supported) - No table reference: assigned to the first table's view but commented out ## Limitations Certain Snowflake features do not have direct equivalents in Count. During conversion, unsupported definitions are included as commented sections with an inline explanation, so nothing is silently dropped. ### Private Access Fields Fields with access_modifier: private_access are commented out in the converted output, as Count does not have an equivalent access control concept for individual fields. ### Cross-View Metric Expressions Model-level metrics that reference fields from multiple tables are not supported. These are commented out with an explanation. ### Snowflake-Specific Properties Properties such as synonyms, sample_values, cortex_search_service, cortex_search_service_name, is_enum, and unique on fields are not converted. non_additive_dimensions on metrics is also not supported. These are noted as unsupported properties in comments on the generated output. ### Verified Queries and Custom Instructions verified_queries, custom_instructions, and module_custom_instructions at the model level are not converted, as Count does not have equivalent concepts. ### Filters Snowflake filters defined on tables are not converted, as Count does not have an equivalent filtering concept at the view level. ### Cross Join Type The cross join type is not supported. Relationships with this join type are commented out. ### Field Expression SQL Field expressions can only use a limited SQL dialect that Count uses in various places such as visuals and low-code cells (see here). Complex SQL constructs, warehouse-specific functions, or deeply nested subqueries may not convert successfully. #### Open Semantic Interchange support URL: https://learn.count.co/build-trusted-context/count-metrics/third-party-file-support/osi-support Use or import OSI (Open Semantic Interchange) files in Count Metrics. Count supports importing and on-the-fly conversion of OSI (Open Semantic Interchange) files into Count catalog views and datasets. This allows teams to maintain their semantic layer in OSI and use it in Count. Not all OSI features are supported. See Limitations for details. ## General support OSI files are just one type of third-party file that Count Metrics supports. This support includes: - on-the-fly (or automatic) conversion for teams who want to continue maintaining their semantic layer definitions outside of Count; - once-off (or manual) conversion for teams who want to fully migrate their existing semantic layer definitions into Count; and - extending automatically converted views and definitions to adjust them without needing to change the third-party files. See here for more details on how Count Metrics supports third-party files generally. This page will focus just on the specific details of this related to OSI files. ## OSI Conversion Details OSI (Open Semantic Interchange) is a vendor-neutral open standard for defining and exchanging semantic model metadata across BI, analytics, and AI platforms. See the core specification for full details. ### What Is Converted - OSI semantic model -> Count dataset - OSI dataset with source -> Count view with table source - OSI field -> Count field (typed as string by default) - OSI field with dimension.is_time -> Count field with timeframes (typed as `date`) - OSI metric -> Count field with aggregate (parsed from expression) - OSI relationship -> Count join - OSI primary_key -> Primary key fields on view ### Supported Types OSI fields do not carry explicit type information. All fields are converted as string by default, except fields with dimension.is_time: true, which are converted as date. ### Supported Aggregation Types Metric expressions are parsed for standard SQL aggregate functions: count, count_distinct, sum, avg, average (converted to avg), median, mode, max, min, stddev, stddev_pop, stddev_samp, var_pop, var_samp, variance (converted to var_samp). ### Supported Timeframes Time fields (those with dimension.is_time: true) are converted with the following timeframes: year_trunc, quarter_trunc, month_trunc, week_trunc, day_trunc, hour_trunc, day_of_week, and the raw (untruncated) value. ### Multi-Dialect Expressions OSI supports expressions in multiple SQL dialects. During conversion, the ANSI_SQL dialect is preferred. If no ANSI_SQL dialect is present, the first available dialect is used as a fallback. The supported dialects in the OSI spec are: ANSI_SQL, SNOWFLAKE, MDX, TABLEAU, DATABRICKS. ### Relationships and Joins OSI relationships are converted to Count joins using from_columns and to_columns to build the join constraint. Joins are placed on the from dataset's view, joining to the to dataset. The relationship type (one_to_one, one_to_many, many_to_one, many_to_many) is inferred based on whether the join columns form a primary or unique key on each side of the relationship. ### Model-Level Metrics Metrics are defined at the semantic model level in OSI and are distributed to dataset views by analyzing datasetName.fieldName references in the metric expression: - Single-dataset reference: assigned to that dataset's view as a normal metric field - Multi-dataset reference: assigned to the first referenced dataset's view but commented out (cross-view field expressions are not supported) - No dataset reference: assigned to the first dataset's view but commented out ## Limitations Certain OSI features do not have direct equivalents in Count. During conversion, unsupported definitions are included as commented sections with an inline explanation, so nothing is silently dropped. ### Cross-View Metric Expressions Metrics that reference fields from multiple datasets are not supported. These are commented out with an explanation. ### AI Context The ai_context property on fields, datasets, metrics, relationships, and semantic models is not converted, as Count does not have an equivalent concept. ### Custom Extensions The custom_extensions property (vendor-specific data) on fields, datasets, metrics, relationships, and semantic models is not converted. ### Non-ANSI SQL Dialects Only the ANSI_SQL dialect is fully supported for field and metric expressions. Expressions in other dialects (SNOWFLAKE, MDX, TABLEAU, DATABRICKS) are used as a fallback but may contain dialect-specific syntax that does not convert successfully. ### Field Expression SQL Field expressions can only use a limited SQL dialect that Count uses in various places such as visuals and low-code cells (see here). Complex SQL constructs, warehouse-specific functions, or deeply nested subqueries may not convert successfully. ### Count Metrics Query Performance URL: https://learn.count.co/build-trusted-context/count-metrics/performance-in-count-metrics >- Catalogs can run either on your database or be cached on our servers. Catalog caching speeds up queries by keeping local copies of the source tables your views use. When a view is created, the system copies the original table onto our server and compiles a query based on the view’s fields and dataset. When users explore the catalog, it queries the table copies using its compiled query. Caching in Count Metrics is available at the workspace level, enabling query results to be stored and reused across multiple canvases. This reduces database query load, improves performance, and ensures faster data retrieval. ## Setting up caching in the catalog You can set up caching at an individual view level, or across all views by making use of the count_catalog.yml file. See the pages linked above for information about set up. ## DuckDB on the server In order for caching to work, we run the query for the view on your database and cache this result on our servers. Any queries using this view will then be run outside your database by Count, either in DuckDB on the server or in your browser, and they will use the cached result (it may first need to regenerate the cache if it has expired). Let's suppose someone opens a canvas with a visual that references a view with caching enabled. The following steps will occur: Step 1 First, the view queries for your database are executed and the results are returned to your browser (if caching is enabled for the view, then cached results may be returned). Only the first 10,000 rows of results are returned. Note: Note Note - when running view queries on your database, they will have no row limit applied. If you would like to reduce the amount of data these queries return, add an explicit limit to the SQL definition in the view. Step 2 Based on the results from step 1, Count decides how to execute the rest of the queries for the view. Queries are executed with DuckDB on the server if: • Any database queries returned more than 10,000 rows • Your local DuckDB database is nearing its memory limit Queries are executed in your browser if: • All database queries returned fewer than 10,000 rows Step 3 Now that all of the view queries have been completed, the visual cell in the canvas will be executed. Count will apply the same logic to decide whether to execute the visual in your browser or on the server. Either way, it will not send a new query to your database if the view is using caching (until the cache expires). Finally, suppose the visual is edited and a new query needs to be run. Rather than running steps 1 and 2 again, Count will re-use the results for any referenced views and only run the queries for the visual in step 3. ## Cached results You can see the information about cached views by clicking on the purple view name post-it on catalog page. This will take you to the view information, which includes the fields, a list of the canvases where the view is referenced, and information about the cached results. The "Exposed" result is the DuckDB result that's referenced in canvases. It's the outer-most cell/query of the view. There will only be one of these per view. The "Source" results are the queries are any dependencies defined in the view source. ### Using The Catalog URL: https://learn.count.co/build-trusted-context/count-metrics/using-the-catalog Get started working in Count from a Count Metrics catalog. [Video: Exploring Catalog Data] [object Object],[object Object] Once you’ve connected your catalog to the project, you have two options on how to access and interact with your data: 1. From a new canvas 2. From the explore page ## Exploring a catalog If you want to do some quick data exploration from your catalog, navigate to a project where the catalog has been imported and select Explore. This will take you to an ephemeral canvas containing a single cell. Select your catalog from the source list on the right hand side and select the dataset from the dropdown beneath it. From here, you can access your view data and use the low-code drag and drop functionality to create your desired visual or table. To save any changes you make, click Save as canvas in the top-right corner. This will save the current state of the visual in a new canvas with that single cell. Without saving, any changes will be lost once you navigate away from the page.\ ## Using a catalog within a canvas Catalogs imported into the project will appear in the source list on the left sidebar of the canvas. You can access these from an existing canvas or by clicking New canvas from the project homepage. Catalogs behave similarly to database connections, but with one key difference: • Only visuals, low-code cells, and control cells can be directly attached to a catalog, • SQL, Python cells, and CSV files cannot be attached to catalogs, however you can write SQL or Python from a table built using the catalog if you have analyst level permissions. Additionally, the caching behavior for results from catalog cells within a canvas follows the default caching settings of the canvas, just like other cells. You can see all information about views & their caching status from the canvas side bar: ## Troubleshooting Runtime error in cell If you're seeing a runtime error returned when you're running a cell from a catalog, it could be a BigQuery permissions issue. YIf you have enabled the BigQuery Storage API, make sure you've given the BigQuery service account the additional permissions it requires: bigquery.readsessions.create bigquery.readsessions.getData #### Explore From Cell URL: https://learn.count.co/build-trusted-context/count-metrics/using-the-catalog/explore-from-cell Dive into the details behind cells with ephemeral no-code explorations. The Explore cell feature in Count Metrics enables users to dive deeper into data directly from a visualization within a shared canvas. This feature streamlines the process of running additional analysis and gaining insights without disrupting the context of your current work. ## How it works 1. Click & explore - select a visualization in a canvas and click the Explore cell icon to begin. 1. Analyze & customize - the visualization will open in a new tab, where you can add additional data layers and explore the data further. 2. Decide next steps - once you’ve completed your exploration, you have two options: 3. Save & share - if you choose to save the visual, select a project to save it to. This opens the new canvas, where you can continue your analysis, add notes or labels, and share it with stakeholders for feedback. The Explore cell feature enhances data exploration, allowing for easy navigation between visualizations and enabling efficient collaboration and decision-making. --- # Integrating Count Learn more about how to connect Count to other tools, from using it in agentic tools like Claude or Cursor, to controlling it programmatically via the API, to bringing it into Slack. ## MCP Server URL: https://learn.count.co/integrating-count/mcp-server How to use Count's MCP server ### Overview The Count Model Context Protocol (MCP) server provides a set of tools that AI apps and agents can use to interact with your Count workspace. The MCP server is available on Pro plans and above. Connect Each workspace has a distinct MCP server URL - to find yours, head to the MCP tab in your workspace settings. The URL should look something like the following, where abc123 is unique for your workspace: Connect with Cursor Add the following to your mcp.json file (where you've replaced abc123 with the correct value): Connect with VSCode Add the following to your mcp.json file (where you've replaced abc123 with the correct value): Connect with Claude Code Enter the following command in your terminal (where you've replaced abc123 with the correct value): Connect with Claude Desktop ### Step 1 - add a custom connector This step needs to be performed once per Claude organization. Note: You need to be a Claude owner Only Claude organization owners can add custom connectors - if you're not an owner, please ask one of the owners of your organization to add Count. Once Count has been added as a connector, anyone in the Claude organization can use it. - Head to the Customize tab - Click the plus icon, then Add custom connector - Enter the URL for the MCP server for your workspace ### Step 2 - connect to the Count MCP server This step needs to be performed by anyone that wants to use the Count MCP server. - Head to your Claude Desktop settings - Choose Connectors - Find the Count connector and choose Connect Regardless of the app you're connecting, you'll need to: - Be at least a member of the workspace (not a guest) - Be signed into Count - Connect to a workspace with the MCP feature enabled The Count MCP server uses OAuth authentication, and once authorised and connected your OAuth client will appear in the MCP tab of your workspace settings: If an app is not authorised within 24 hours, its OAuth client is deleted and authentication will have to take place again. After authorisation, apps are authenticated for the next 90 days, after which they'll need to be authorised again. ### Using the MCP server Once connected, your AI agent has the same permissions as you do when interacting with resources in Count. It can: - Search the workspace - View workspace resources - Run queries - Export CSV files - Create agents in canvases See the full list of MCP tools and their functionality in the MCP reference page in your workspace settings. ## Public API URL: https://learn.count.co/integrating-count/public-api How to use Count's public REST API. ### Overview The Count API is REST-based, uses standard HTTP methods, accepts JSON-encoded request bodies and returns JSON-encoded responses. All endpoints follow RESTful conventions for resource manipulation and use standard HTTP status codes to indicate success or failure. The API is available on Scale plans and higher. To use the API, first create a service account and generate an API key (see below). Include your API key as a bearer token in the Authorization header of each request: ### Service accounts View the service accounts for your workspace in the API tab of your workspace settings: After creating a service account, an API key will be displayed for you to download. API keys are only ever shown once - make sure you save it. Service accounts are granted permissions like other members of your workspace - ensure that they have appropriate access to the required resources. To change the workspace role for a service account, select it from the service accounts list: If a service account or API key is deleted, that key or keys are immediately revoked and cannot be restored. To safely roll credentials without interruption, create a new API key and start using it before deleting the old one. ### API responses Responses are returned as JSON-encoded strings with the form: Response status codes follow HTTP conventions to represent the success or failure of an API request - the 2xx range represents a successful response, the 4xx range represents a client error, and the 5xx range represents a server error. ### Rate limiting API requests are rate limited to ensure system stability. Check the rate limit headers returned in each response to monitor your usage: - RateLimit-Limit - Maximum requests per window - RateLimit-Remaining - Remaining requests in this window - RateLimit-Reset - Time when limit resets - Retry-After - How long until the limit resets ### API methods View the available API methods from the reference page in the API tab of your workspace settings. Click on any method to build requests interactively: View the OpenAPI spec for your region at: - US - https://api.app.count.co/v1/openapi.json - EU - https://api.eu.count.co/v1/openapi.json ## Slack URL: https://learn.count.co/integrating-count/ai-agent-slack Using Count's AI Agent from Slack Kick-off some analysis using Count's AI agent without leaving Slack. Start a new thread for a new question, or have the agent weigh in on a discussion in an existing thread. The agent will respond in the same thread, and you can ask follow up questions to dive deeper. Note: Slack notifications You can also use the Slack integration to receive notifications and alerts. See here for details about this. ## Install the Count app for Slack Before you can interact with Count's AI agent from Slack will first need to install the Count app for Slack. Install the app by visiting your user account settings (accessed by clicking on your avatar icon in the Count workspace > Account) and clicking the Connect Slack button. Once installed, see the instructions below to start talking with the AI agent. Read about how Count uses your data in our Privacy Policy. ## Interacting with the agent from Slack You can start a new agent (in a fresh canvas) in the following ways: - Mention the Slack app in a channel (e.g. "@Count can you help me understand why our sales dropped last month?") - Mention the Slack app in an existing thread (e.g. "@Count do you have any insights on this?") - DM the slack app directly (e.g. "Hey Count, can you help me understand our customer churn?") If you haven't used the Slack app in a channel before, you likely need to do two things first: - Invite the Slack app to the channel (Slack should prompt you to do this when you mention the app) - Select a project for the new canvas (the app will prompt you to do this) When a new agent is started, a link to the canvas will be shared in the thread and when it's finished it will post its response, some suggested next steps, and a screenshot of what it's created or changed in the canvas. For existing agent threads in Slack, you ask follow up questions by: - Mentioning the Slack app in the thread (or just replying in the thread for DMs) - Clicking one of the next steps buttons in the agent's response ## Project / channel mappings When you ask a question and select a project, you'll be asked if you want to always use that project when you ask questions in that channel. This is called the project/channel mapping. You can manage this using the following slash commands: - /count set-project opens a modal to select a project - /count unset-project removes the project/channel mapping for the channel - /count project shows the current project/channel mapping for the channel ## Sync between Slack and the canvas in Count The conversation with the agent is synced between Slack and the canvas in Count so you can see the full conversation history in either place. The only difference is that we don't send all of the agent's output to Slack as it would be too noisy. This is true for both the initial response and responses to any follow up questions. You can also ask interact with the agent from either UI. Ask follow up questions or approve/reject agent database requests from Slack or the canvas. ## Permissions Your Slack user is linked to your Count user and any actions like starting or interacting with an agent will be done on behalf of your Count user. The same permissions apply as if you were using Count directly. The main difference is that other users in the Slack channel who don't have access to the project/canvas, while they won't be able to interact with or start agents, they will still be able to see the agent's responses in the channel. This is important to keep in mind when sharing insights from the agent in Slack channels. --- # Managing Your Workspace Learn more about Count's permissions, telemetry and, security and governance controls. ## Projects URL: https://learn.count.co/governance-and-administration/project-settings The organisational unit of the Count workspace. Projects organise your canvases and reports around a common data source and provide a space where multiple users can collaborate together. Projects contain: - A list of canvases and reports. - A group of users who can access the project with different levels of permissions. - Optionally, a reference to a data source. If none is selected, then only CSV files can be analysed in the project. ## Project naming conventions When creating projects, we can use naming hierarchies to organize as we scale. You can create projects for individual work, department and initiative work, and then company wide. ## Getting started You have a few options to start adding to your project: 1. New canvas - add a blank canvas to begin creating. 2. Explore - with a data source connected, you can launch straight into a low-code cell, ready for quick data analysis. 3. Templates - select a template to get going quickly whilst using a consistent structure. ## Canvases The project home page shows all the canvases stored within the project. To see available options for each canvas, right-click on the canvas or click the menu icon. ## Pinning canvases You may pin any number of canvases to a project by clicking the Pin to project option in the canvas option menu. When a canvas is pinned it always appears above the canvas list. Un-pin a canvas by right-clicking on the pinned canvas and select Remove from pinned. If a canvas is moved to another project, it will not automatically be pinned in that project. Use pinned canvases to highlight the main results you wish to emphasise in a project. ## Managing data Only project admins can change the data accessible by a project. Selecting the Manage data button on the project home page allows control of the data source accessible by canvases within the project. You are able to connect any data source you have permission to view, even if the rest of the project members cannot normally view that source. Be aware that adding a data source to a project means that the other project members may be able to view information from this data source from within project canvases. ## Managing project access The list of project members can be viewed from the Manage access button in the project home page. Member access and permissions can be updated by project admins or workspace owners. All other project members can view the member list, and may be permitted to invite other users as viewers if the Allow sharing option is enabled (see below). ## Share a project with the workspace Project admins are able to assign a workspace-wide role to a project. While this permission is active the project will be accessible to every workspace member (workspace guests must be invited explicitly). The workspace-wide roles are: - Report viewer - workspace members can view reports in this project - Viewer - workspace members can view canvases - Editor - workspace members can edit canvases - Up to analyst - workspace members can edit canvases, and workspace analysts (or above) can edit code. Where a user has a specific project role already, their overall project role is determined by the most permissive of their specific role or the workspace-wide one. ## Sharing a project with a workspace member Whether a new user can be invited to a project depends on the role of the user sending the invitation, the project settings, and the workspace settings. Options for workspace admins and owners Workspace admins and owners can invite users to a project as either admins (if the user is a workspace admin), editors, viewers or report viewers. If the workspace doesn't allow guests then only existing workspace users can be added to the project. If guests are allowed then anyone can be invited to the project as a viewer. If the user being invited is covered by the workspace domain whitelist, then this user can be invited as either an editor or a viewer and is automatically added as a workspace member (they cannot be added as a guest). Options for workspace members and guests Other project members can invite users to the project only if the Allow sharing option is enabled (see below). These invited users can be new or current members of the workspace. New users will become either workspace guests or members depending on the workspace domain whitelist settings. More details on the different project roles can be found in the roles and permissions page. ## Project settings The project settings can be accessed from the Manage project button on the project home page, and are only accessible by project admins and workspace owners. From this menu you can: - Change the project name - Delete the project - Control sharing - Manage agent context - Configure Python network access and secrets Allow sharing This setting determines whether users with editor or viewer permissions in a project can invite other users as viewers to the project or share individual canvases with users outside the project. By default this setting is on. If the setting is turned off, only admins can invite users to the project and share documents to users outside of the project. Python settings This section shows the network restrictions in place for the project (controlled at the workspace level) and allows project-specific secrets to be defined, which can be used in network requests in Python cells for canvases. Secrets must specify the domains to which they can be sent. ## Agent Context Agent Context allows for context to be provided and included globally on all agent queries within the project. This will be combined with any workspace-level context set by the workspace-owner, and then the actual user-provided prompt within individual canvases. You can see suggested best practice for context here. Workspace and project context is concatenated together and included with agent queries. The agent is instructed to prioritize project-level context over workspace-level context. ## Roles and permissions URL: https://learn.count.co/governance-and-administration/roles-and-permissions User permissions for workspaces and projects in Count. Count's permissions model helps teams of different sizes to work flexibly whilst maintaining strong governance over who can access the team's data and analysis. A user's access is governed by: - Their workspace role. - Any groups they are a member of. - The projects they can access. - The role they have within each project. You can view everyone with access to the workspace in the Members tab in the workspace settings. ## Workspace roles There are several workspace roles in Count, which determine the actions workspace members are permitted to perform. Roles are hierarchical, where Owner is the most permissive role and Guest is the least. ### Owners Owners have full control of the workspace. They automatically have access to every connection and project and always have administrative privileges in each. By default the creator of the workspace becomes an owner, and a workspace can have multiple owners. Owners are always billable. Owners can: - Access and change all workspace settings. - Create, edit and delete all database connections. - Create, edit and delete catalogs. - Have Admin roles in all projects. - Create projects. - Manage members and roles. Owners cannot: - Change their own workspace role. - Leave a workspace if they are the only Owner. ### Admins Admins control how data is accessed within the workspace. They manage all database connections and build and manage projects. Admins are always billable. Admins can: - Create database connections. - Be given Admin or Viewer roles within any database connection. - Create projects. - Be given Admin, Analyst, Editor or Viewer roles within any project. - Be given Analyst or Viewer roles within any catalog. - View (but not edit) workspace settings. - Manage members and roles. Admins cannot: - See every project, catalog or connection in the workspace by default - they have to be invited. - Change workspace settings. - See workspace billing settings. - Change their own workspace role. ### Analysts Analysts are workspace members that may be given permission to edit code in canvases. Analysts are always billable. Analysts can: - Be given Analyst, Editor or Viewer roles within any project. - Be given Analyst or Viewer roles within any catalog. - View the list of members in the workspace. - Be given access to catalogs as viewer or editor. Analysts cannot: - See or edit any database connections by default. - See or edit any catalog by default. - Be given Admin roles for any project. - See the Settings and Billing tabs in workspace settings. ### Members Members are like Analysts, but cannot be granted permission to edit code in any canvases. Members are never billable. If given edit access to a canvas, Members can edit any part of the canvas except for cells and visuals. ### Guests Guests are users who have not been invited to join the workspace but have been given access to specific canvases and projects within the workspace. Guests are never billable. Guests can: - Be given Viewer or Report Viewer roles within any project. - Be given Viewer or Report Viewer roles for a specific canvas. Guests cannot: - See any workspace settings. - See any database or catalog connections. - Be added to groups. - Be invited to projects or canvases via the "Members of workspace" permission. ## Project roles Within each project every member also has a project-specific role. These roles dictate which project-level actions users can perform: ### Viewers / Report viewers Viewers / Report viewers can: - View canvases that are shared with the project (if a viewer) - View reports that are shared with the project - View all members of the project - If allowed by the project settings: share canvases outside the project or invite new users to the project as Viewers (if a viewer) or Report viewers - Leave the project ### Analysts / Editors Analysts / Editors can additionally: - Create, view, edit and delete canvases - Restore deleted canvases - View canvas version history - Edit cells and visuals (if an analyst) ### Admins Project Admins must have a workspace Owner or Admin role. Admins can additionally: - Manage project membership and roles - Manage available connections - Update project settings - Delete the project If a user has been assigned two conflicting roles then the most permissive role wins. For example, if a user has explicitly been granted a project viewer role but in addition the project has granted edit access to the whole workspace, then the user will have edit access. ### Troubleshoot Why is the option to set workspace-level permissions greyed out? Don't worry - that's expected behavior! If the project containing the canvas is already shared with the workspace, this option is disabled because it has no additional effect. Since workspace-level access has already been granted at the project level, changing the permissions in the canvas won't make any difference (the most permissive permission always takes precedence). If you hover over the disabled option, a tooltip will appear to explain this, which looks like this: ### Groups URL: https://learn.count.co/governance-and-administration/roles-and-permissions/groups Simplify your user permissions by grouping users. The Groups tab allows workspace owners and admins to manage groups of workspace members. Groups are a convenient way to manage common permissions for a set of users. For example, groups can be assigned roles in projects, or permissions on canvases and reports. ## Create a group When creating a new group, you may assign the following options: • Name - the public name of the group displayed to other workspace members • Workspace role (optional) - members of this group will be assigned this workspace role (if it is higher than their individual workspace role). ## Add group members To add members to an existing group, expand it and select Add members: Note: Info Workspace guests cannot be assigned to groups, so will not appear in this list. ## Delete a group If a group is deleted, all group members remain members of the workspace, but: • Any workspace roles conferred on those users due to their group membership expire. • Any permissions assigned to those users due to their group membership cease to take effect. Therefore you should be aware that while group deletion is a non-destructive operation, it may cause changes to permissions for group members that you do not expect. ## Workspace Settings URL: https://learn.count.co/governance-and-administration/workspace-settings Control how your team uses Count. The workspace settings page is where workspace owners and admins manage workspace-wide settings. Note: Info You can change your personal Count account settings from the avatar icon in the top right of the screen. ## General settings ### Workspace name Workspace names can be any combination of letters, numbers and symbols (including emojis 👍). Name the workspace after your company or team. ### Domains You can whitelist specific website domains to give users with matching email addresses automatic access to your workspace. Whitelisted users will automatically see an invitation to your workspace when they first create an account. If they do not accept the invitation to join, they will continue to see a pending invitation in the workspace selection menu. If a whitelisted user doesn't have a Count account and is invited to a specific project or canvas they will also automatically become a workspace member. ## Sharing settings ### Disable public links This setting prevents users being able to share canvases publicly. If this setting is disabled and there are already public canvases in your workspace, those canvases will lose their public access. ### Enable data in public thumbnails If this setting is enabled, thumbnails for public canvases will contain query results. Note that enabling this setting can cause increased load on your database, as thumbnail generation may result in the execution of additional queries. ### Disable workspace guests This setting prevents projects and canvases being shared with users who are outside of the workspace and do not have a whitelisted email address. Note: Warning Enabling this setting will instantly remove all guests from any projects or canvases and cannot be reversed. ### Disable embeds If this setting is enabled, Count will refuse to load canvases for this workspace when embedded in an iframe in other sites. This setting applies to all existing embeds in addition to any new ones, and can be safely enabled or disabled at any time. ### Disable public alerts If this setting is toggled on, meaning public alerts are disabled, Count will only send alerts to users that are permitted to view the canvas that generated the alert. Note that disabling this setting does not grant access to any canvases, it only affects the delivery of alert notifications. This setting must be disabled to allow sending alerts to arbitrary email addresses. ## Query settings ### Disable automatic cell execution in new canvases If this setting is enabled, new canvases will default to manual cell execution. This setting can be overridden per-canvas from the query menu. ### Use DuckDB by default for referenced cells When you create a new cell using the “reference cell” button, it will default to running in DuckDB if this setting is enabled. Keeping this enabled can reduce queries to your data warehouse by using cached data instead. ### Setting the default start day of the week Any day can be selected as the first day of the week and will reflect in weekly data in your queries and visualisations across the workspace. For example, if you set Monday as the start of the week, all of your weekly reports and charts will display data from Monday through Sunday. ### DuckDB server timeout Sets the maximum time (in seconds) a DuckDB query can run on the server before it is automatically stopped. ## Data settings ### Disable caching of query results This setting prevents caching of query results, and prevents users from enabling this option within canvases. Enable this setting if you want to ensure that your data is never stored by Count. ### Default cache duration for new canvases This setting sets the default cache duration for any new canvases. This option can be overridden per-canvas. Read more about the effects of query caching here. ### Disable CSV downloads This setting disables the ability to download CSV files from any canvas cells or visuals. ## Python settings The Python settings configurable at a workspace level include the ability to control network access of Python cells and to specify secrets that can be used in network requests made by Python cells. ### Restrict network access Network access for Python cells can either by unrestricted or restricted. The former means network requests can be made to any public domain. The latter means they can only be made to the domains that you specifically configure. ### Secrets Python cells can reference secrets which can be used in network requests (see Python cells for more details). These must be scoped to specific domains and can optionally be limited to only specific projects. Secrets can also be configured at the project level via the project settings. ## Deleting the workspace This requires explicit confirmation after the option is selected by typing in the name of the workspace. Once deleted a workspace and its contents cannot be restored - please double check that the deletion is intentional! ## Manage other workspace features Read more about other workspace settings in the following pages: - Workspace members - Groups - Tags - Brand - AI - Billing - SSO ### Workspace Members URL: https://learn.count.co/governance-and-administration/workspace-settings/workspace-members Get an overview of all the users across your workspace. The Members tab allows workspace owners to see all workspace members and guests, and change the workspace role of a user. In this tab, you can also invite new members via email and remove users from the workspace. Note: Info If the role of a workspace member is changed to Guest, then they will be removed from any groups they are a member of. To learn more about workspace roles and permissions, see this page. ### AI settings URL: https://learn.count.co/governance-and-administration/workspace-settings/ai-workspace Control Count AI Agent workspace settings, enable/disable globally, and add shared context that combines with project prompts for richer, more consistent answers. At a workspace-level, there are two options that for the Count AI Agent, settable by workspace owners. The first enables or disables the agent globally. This defaults to enabled. Agent Context allows for context to be provided and included globally on all agent queries within the workspace. This will be combined with any project-level context, and then the actual user-provided prompt. You can see suggested best practice for context here. Workspace and project context is concatenated together and included with agent queries. The agent is instructed to prioritize project-level context over workspace. ### Billing URL: https://learn.count.co/governance-and-administration/workspace-settings/billing Control your workspace's billing preferences. If your workspace has begun a paid subscription, here workspace owners can: - Update their payment information. - Provide a Tax ID. - See their workspace balance. - See any historical invoices and outstanding payments. More information on billing and workspace plans can be found in the Pricing FAQ. ### Brand URL: https://learn.count.co/governance-and-administration/workspace-settings/brand Customise Count to your company colours and branding The Brand tab allows workspace admins to upload custom fonts to Count, which can then be used in text, stickies, shapes, tables and visuals in any of your canvases. Custom fonts are available to all workspace members. Note: Info Custom workspace fonts are available on the Enterprise Plan. ## Uploading a custom font To upload a custom font to Count, click Upload fonts and select one or more OTF or TTF font files from your computer. Note: Warning Count does not currently support variable font files. Fonts that have uploaded successfully will appear in a list and can then be immediately used throughout your canvases. ## Deleting a custom font To delete a custom font, click on the ellipsis next to the font and select Delete. ### Tags URL: https://learn.count.co/governance-and-administration/workspace-settings/tags Catagorize your canvases using customizable tags. Tags help you organize your work, allowing you to assign statuses and categories to your canvases. They provide a convenient way to classify canvases between projects, but do not have any effect on permissions. Note: Info Tags are available on the Team, Scale and Enterprise plans. Workspace owners and admins can manage the tags available in the workspace, and any workspace member can add or remove tags from the canvases they can edit. ## Managing tags By default, each workspace contains four tags: • In Progress • Needs Review • Live • Archived ## Creating tags Workspace owners and admins can add custom tags from the workspace settings. Click on "Add tag" to create a new custom tag, and give it a name, color and (optionally) a description. Any workspace member can now assign the custom tag to canvases throughout the workspace. ## Editing tags The name, color and description of existing tags can be changed from these settings. ## Deleting tags Tags can also be deleted from the workspace settings. Note: Danger Deleting a workspace tag will remove it permanently from all canvases. Note that this action cannot be undone. ## Assigning tags to canvases Any workspace member with edit access to a canvas can add or remove tags. To do this, head to the project that contains the canvas, and click on "Add tag" below the thumbnail (if viewing in a grid) or in the table row (if viewing as a list). From there you can select the tags you want to assign to the canvas, and — if you are a workspace admin or member — you can add new tags if necessary. ## User settings URL: https://learn.count.co/governance-and-administration/user-settings Edit your account preferences There are a number of settings available at a user level. Here you are able to: - Change your display name - this is how other Count users will see you. - View your email address - currently your email address cannot be changed. Please contact Count support if it needs to be changed. - Receive notifications - opt in or out of email and Slack messages for this workspace. - Connect Slack - here you can choose to link your Count and Slack accounts to receive comment and alert notifications in Slack. - Leave the workspace - note that if you are the sole workspace owner, you cannot leave the workspace. You can either delete the workspace, or promote another workspace member to the Owner role. ## Telemetry URL: https://learn.count.co/governance-and-administration/telemetry Deep, daily-refreshed telemetry for Count: track queries, canvases, users, and AI agents with curated datasets and SQL access for performance, adoption, and audit insights. Count Telemetry gives workspace administrators deep visibility into how their Count environment is being used, from query performance and user activity to canvas engagement and AI agent behaviour. Count telemetry is available on Scale plans and above. ## Access & Permissions - Who has access by default: Workspace Owners are automatically granted access to telemetry data. - Granting access to others: Owners can share access to the telemetry connection in exactly the same way as any other database connection or project in Count, via the standard permission management UI. - API access: Your telemetry data is also accessible via the Count API. - A project named 'Admin telemetry' is also available and has a pre-populated canvas 'Query troubleshooting' which allows you to explore performance in your workspace. ## What is available Count Telemetry is exposed in two complementary ways: ### 1. The Count Telemetry Database Connection A BigQuery database connection (called Count Telemetry) provides direct SQL access to the underlying raw telemetry tables. The connection is refreshed once per day (between 4 and 5am UTC) The database contains the following tables - Table: `canvases` - Description: One row per canvas. Includes title, project, cache settings, alert config, and creation timestamp. - Table: `cells` - Description: One row per cell. Includes type (SQL, Python, visual, table, CSV), connection, and execution settings. - Table: `queries` - Description: One row per query execution. Includes duration, status, error, query engine, and user. - Table: `users` - Description: One row per workspace user. Includes name, email, role, and query activity aggregates. - Table: `canvas_loads` - Description: One row per canvas load event. Includes user, timestamp, load duration, and whether it was a report view. - Table: `cell_edits` - Description: One row per cell edit event. Includes user, timestamp, and edit type. - Table: `daily_edits` - Description: Aggregated daily editing activity per canvas and user. - Table: `downloads` - Description: One row per data download event from a cell. Includes user, canvas, cell, and timestamp. - Table: `app_errors` - Description: Application-level network errors. Includes error type, canvas, user, and timestamp. - Table: `agent_history` - Description: Full execution log of AI agent (Count AI) sessions. Includes sequence, type, role, content, and errors. - Table: `agent_queries` - Description: One row per query submitted by an AI agent. Links to the `queries` table via `query_key`. - Table: `agent_feedback` - Description: Feedback recorded against AI agent interactions. - Table: `connections` - Description: One row per database connection. Includes name, type, cache settings, and concurrency limits. - Table: `projects` - Description: One row per project in the workspace. - Table: `canvas_permissions` - Description: Canvas-level permission assignments (user, role, type). - Table: `canvas_permissions_resolved` - Description: Resolved effective permissions per user per canvas. - Table: `project_permissions` - Description: Project-level permission assignments. - Table: `keys` - Description: Central activity event log linking canvases, cells, users, connections, and events. - Table: `workspace` - Description: Workspace-level configuration: default cache settings, memory limits, DuckDB config. - Table: `groups` - Description: Workspace user groups. Note: Improvements were made to the telemetry data on 15 June 2025, as a result some fields do not include data prior to this. This includes detailed query timing (queue, execution, extraction duration), query engine context, access mode, scheduled refresh flags, and monthly totals. Fields without a cutoff have full historical data. ### 2. The Admin Telemetry Catalog The Admin Telemetry catalog provides a curated semantic layer on top of the raw telemetry tables. It is the recommended way to explore telemetry data — fields are pre-defined, labelled, and join logic is managed automatically. Like the database, the catalog is refreshed once per day. Note that the Queries table in the catalog is restricted to a rolling 30-day query execution log. Use the database connection directly for full query history. The catalog exposes 5 datasets, each combining multiple views: ### Dataset: Assets Centralized activity dataset mapping canvases, cells, permissions, and all system event actions. The broadest dataset. Joins the keys event log to canvases, cells, users, connections, permissions, and all event types (edits, loads, downloads, errors, agent activity). Use this for cross-entity analysis or building a full audit trail. Joined views: keys, canvases, cells, cell_edits, connections, app_errors, canvas_loads, canvas_deletions, daily_edits, downloads, project_permissions, canvas_permissions, canvas_permissions_resolved, projects, users, workspace, agent_history ### Dataset: Queries Rolling 30-day query execution log with performance details. One row per query execution. Joins to cells, canvases, projects, connections, users, monthly totals, cell ownership, and agent attribution. Use this to understand query volume, performance, errors, and who is running what. Key fields include: queries.duration_ms, queries.status, queries.error_type, queries.full_context (engine: database, duckdb, duckdb-server, cache, python), queries.query_role (editor, viewer, scheduled, alert), queries.started_at. Joined views: queries, cells, canvases, projects, connections, users, queries_monthly_totals, cell_owner, agent_queries ### Dataset: Agent Analytics End-to-end view of AI agent (Count AI) activity. Combines agent execution history with the queries those agents submitted. Use this to understand how often Count AI is being used, by whom, on which canvases, and how its queries perform. Joined views: agent_history, agent_queries, queries, canvases, users ### Dataset: Canvas Activity Analytics Canvas load volumes and user discovery metrics. Tracks every canvas load event. Use this to understand which canvases are most visited, by whom, how quickly they load, and whether they are being accessed in editor vs. report/viewer mode. Joined views: canvas_loads, canvases, users ### Dataset: Query Development Analytics Cell edit history and development lifecycle tracking. Tracks every cell query edit. Use this to understand which cells and canvases are most actively developed, and by whom. Joined views: cell_edits, cells, canvases, users The following views are available across the catalog datasets: - View: `canvases` - Description: Canvas metadata including title, project, cell counts by type, cache settings, creation date - View: `cells` - Description: Cell metadata including type, connection, alert status, execution and limit settings - View: `queries` - Description: Query executions (30-day window): duration, status, error, engine, access mode, user - View: `queries_monthly_totals` - Description: Monthly aggregated query counts, durations, and error counts by engine - View: `users` - Description: User info: name, email, workspace role, total queries, last active timestamp - View: `connections` - Description: Database connections: name, type, cache/timeout/concurrency settings - View: `canvas_loads` - Description: Canvas load events: user, timestamp, duration, editor vs. report view - View: `cell_edits` - Description: Cell edit events: user, timestamp, edit type - View: `cell_owner` - Description: Derived cell ownership (last editor → most active → creator) - View: `daily_edits` - Description: Daily editing activity per canvas and user - View: `downloads` - Description: Data download events from cells: user, timestamp, editor vs. report view - View: `app_errors` - Description: Application network errors: type, user, canvas, timestamp - View: `agent_history` - Description: AI agent execution log: sequence, type, role, content, errors - View: `agent_queries` - Description: Queries submitted by AI agents, linkable to full query performance data - View: `workspace` - Description: Workspace configuration: cache defaults, memory limits, DuckDB settings - View: `projects` - Description: Project names and keys - View: `canvas_permissions` - Description: Canvas permission assignments - View: `canvas_permissions_resolved` - Description: Effective resolved permissions per user per canvas ## Getting Started Before users can analyse telemetry data, an Owner needs to make it available: - Share the connection or catalog with a project. Go to the Count Telemetry connection or the Admin Telemetry catalog settings and add the project(s) you want to give access to. Users with access to those projects will then be able to query telemetry data from any canvas within them — just as they would any other connection. - Use Count AI to get started quickly. The Count AI agent is a great starting point — open a canvas, describe what you want to understand (e.g. "show me the most active canvases in the last 30 days" or "which users have run the most queries?"), and Count AI will write and run the queries for you using the telemetry data available in the project. ## Learn More For a practical introduction to working with Count Telemetry to monitor and improve your AI agent, watch our webinar: Monitor agent quality and improve it over time: Your agent is in the wild. Real users are asking real questions. Some are getting good answers. Some aren't. How do you know which is which — and how do you systematically make it better? This session covers the operational reality of running a self-serve agent at scale. Mitra and Jason walk through how to monitor agent quality using telemetry data, spot the patterns that signal something's wrong, and update context, schema, and data models based on real usage rather than guesswork. Most teams' agents quietly degrade over the first few months because no one's watching the right signals. By the end of this session, you'll know exactly what to watch and what to do about it. ## Security and Compliance URL: https://learn.count.co/governance-and-administration/security-and-compliance SOC 2 and GDPR on every plan, with HIPAA, SSO, SCIM and data residency on Enterprise. ## Built on a secure foundation Every Count workspace is backed by SOC 2 and GDPR compliant infrastructure, regardless of plan, so security isn't something you have to pay extra for to get the basics right. Enterprise plans add further options for organizations with stricter requirements, including HIPAA compliance and control over where your data is stored. ## Sign in and provision your way Single sign-on lets your team log in with the identity provider you already use, with support for Okta, Google, Azure AD (Entra ID), JumpCloud, and any generic OIDC provider. Alongside this, SCIM provisioning keeps user accounts and access in sync automatically as people join, move within, or leave your organization, and the audit log gives you a full record of activity across the workspace for compliance and security review. ### Single Sign-On (SSO) URL: https://learn.count.co/governance-and-administration/security-and-compliance/sso Simplify the way that your users authenticate to Count using Single Sign-On. Single sign-on (SSO) is available on the Enterprise plan. Please speak to a member of the Count team to discuss enabling SSO for your workspace. ## Configuring SSO for your workspace Count supports OIDC SSO, and is compatible with a broad range of identity providers. See the following pages for more help on the configuration steps required for your provider: - okta - entra-id - jumpcloud - google - generic-oidc ## Domain verification SSO only becomes active once ownership of the appropriate domains has been proven. After adding an SSO domain, a unique verification code is generated. Add this code to your DNS records and select Verify to confirm ownership of the domain. This step is usually quick, but in some cases can take up to 72 hours. Note: Info Once SSO has been configured for a workspace, the email domain whitelist in the workspace settings will have no effect, and the SSO domain list will take precedence. ## SSO options Once SSO is configured and at least one domain has been verified, there are several options to further customise behaviour. ### Enforce SSO If SSO is enforced, users will only be able to access this workspace and its resources if they have most recently signed in using SSO. Public canvases are still visible to everyone if SSO is enforced, but will only be editable if the viewer has signed in using SSO. Note: Info Workspace owners can always log in using any method, regardless of this setting. If you encounter an issue signing in using SSO, contact your workspace owner to resolve the issue. ### Automatic provisioning If this setting is enabled, any user signing in with an email address at one of the verified domains will automatically be added to this workspace with a member role. ### Okta URL: https://learn.count.co/governance-and-administration/security-and-compliance/okta Configure the single sign-on integration between Count and Okta. To connect Count to Okta, you'll need to be both an Okta admin and Count workspace owner, and have SSO enabled for your workspace. Head to the Count workspace settings, select the SSO tab and select Okta - you'll need to provide an Authorization server issuer URI, Client ID, and Client secret. ## Create an Okta application Authorization server issuer URI - this can be found from your list of authorization servers in the Okta admin dashboard. The URI is the value in the third column. You may also need the Audience value if it is different than the default value of api://default. Next, you'll need to create an Okta app from the Applications section by clicking Create App Integration: and then selecting OIDC and Web Application: Finally, customise the following settings: • Name - any memorable name • Sign-in redirect URIs - https://app.count.co/sso-login or https://eu.count.co/sso-login • Sign-out redirect URIs - https://app.count.co/sign-out or https://eu.count.co/sign-out Once you're done, click Save and your application will be created. You'll then be able to copy the Client ID and Client secret and paste them into Count. Note: Access token subject Ensure the sub claim for access tokens generated by the chosen authorisation server contain the user email address. To check what Okta-generated access tokens look like, go to Security -> API -> choose auth server -> Token Preview, and check the form of the token option. ## Add an event hook (recommended) Event hooks are an Okta feature that allows third-party services to subscribe to events happening within Okta. Count supports the Okta User logout and User deactivated event hooks, and is able to sign users out of Count when they are signed out of or removed from Okta. To add this event hook, head to Workflow, then Event Hooks in the Okta dashboard. Please then enter the following settings: • Name - any memorable name • URL - https://app.count.co/api/v1/auth.oktaEventHooks or https://eu.count.co/api/v1/auth.oktaEventHooks • Authentication field - authorization • Authentication secret - copy this value from the Count SSO settings tab. This secret confirms that a given event is related to your workspace. • Subscribe to events - select User logged out from Okta and User deactivated (if sent to Count, all other events will have no effect). Note: Info Once logged in, a user's session in Count may remain valid for up to an hour while their current tab is open. To revoke a user's access immediately, also remove them from the Count workspace in the members tab. ### Google URL: https://learn.count.co/governance-and-administration/security-and-compliance/google Configure the single sign-on integration between Count and Google. To connect Count to Google SSO, you'll need to be a Count workspace owner, and have SSO enabled for your workspace. Head to the Count workspace settings, select the SSO tab and select Google - you'll need to provide a Client ID and Client secret. ## Create an OAuth 2.0 Client ID Head to your GCP project console and select APIs and services > Credentials, then choose Create credentials: When creating an OAuth client, choose the following settings: • Application type - Web application • Authorised JavaScript origins - https://app.count.co • Authorised redirect URIs - https://app.count.co/sso-login After your OAuth client has been created, copy the Client ID and Client secret and paste them into the Count SSO settings form: ### Entra ID URL: https://learn.count.co/governance-and-administration/security-and-compliance/entra-id Configure the single sign-on integration between Count and Entra ID. To connect Count to Entra ID, you'll need to be a Count workspace owner, and have SSO enabled for your workspace. Head to the Count workspace settings, select the SSO tab and select Entra ID - you'll need to provide an Issuer URI, Client ID, and Client secret. ## Create an app registration In Entra ID, head to Applications > App registrations and select New registration: Give your app a recognisable name, and ensure that the Redirect URI is set to https://app.count.co/sso-login then click Register. Find your Client ID from the overview page: Find your Issuer URI by selecting Endpoints and copying the URI in OpenID Connect metadata document: Generate a Client secret from the Certificates & secrets menu by selecting New client secret: ### JumpCloud URL: https://learn.count.co/governance-and-administration/security-and-compliance/jumpcloud Configure the single sign-on integration between Count and JumpCloud. To connect Count to JumpCloud, you'll need to be a Count workspace owner, and have SSO enabled for your workspace. Head to the Count workspace settings, select the SSO tab and select JumpCloud - you'll need to provide a Client ID and Client secret. ## Create an SSO application In the JumpCloud admin dashboard, under User authentication > SSO Applications, select Add New Application then Custom Application: When choosing features to enable, ensure that Configure SSO with OIDC is selected: After your app is created, ensure that the Redirect URIs contains https://app.count.co/sso-login and the Login URL is https://app.count.co/sign-in: Under Standard scopes select Email: Important - once your app is configured, copy the Client ID and Client secret immediately, as you won't be able to see the secret again: You can now paste these values into the Count SSO settings form. ### Generic OIDC URL: https://learn.count.co/governance-and-administration/security-and-compliance/generic-oidc >- To connect Count to a generic OIDC identity provider, you'll need to be a Count workspace owner, and have SSO enabled for your workspace. Head to the Count workspace settings, select the SSO tab and select Generic - you'll need to provide an Issuer URI, Client ID and Client secret. The Issuer URI should be the base path at which the OIDC configuration can be retrieved. For example, if your Issuer URI looks like then a JSON document should be accessible at that contains a valid OIDC configuration document: Count currently assumes that your identity provider: • Returns an OIDC configuration with at least the above properties • Accepts the client_secret_basic authorisation method • Supports the openid and email scopes • Returns an identity token that contains the following in its payload: - email - the email address of the authenticated user - sub - the unique identifier of the authenticated user --- # Analytics Engine The compute layer behind Count's agents: cells, Python, and an in-memory engine that keeps analysis fast and warehouse costs low. ## Count's compute layer URL: https://learn.count.co/analytics-engine/compute-layer The execution engine that lets you and your agents run thousands of queries without hitting your warehouse. Count's compute layer intelligently routes queries between your data warehouse, Count's servers, and users' local machines—reducing warehouse costs while enabling faster, more exploratory analytics. ## Why the compute layer matters The problem: Every query to your data warehouse costs money and takes time. BI tools can consume 30-80% of warehouse costs. When AI agents get involved (running 15+ queries per question), costs can explode. The solution: Run queries where it makes most sense. Small and medium queries run locally or on Count's servers. Only large initial queries hit your warehouse. Result: 60%+ of queries never touch your warehouse. ## How it works Query routing: - Initial query → Runs on your data warehouse to fetch data - Further queries (100MB-32GB) → Run on Count's servers using DuckDB - Small queries → Run directly on user's laptop using DuckDB What this means: - Once data is pulled from your warehouse, you can iterate, filter, aggregate, and analyze without additional warehouse queries - AI agents can run unlimited queries for thorough analysis without cost concerns - Everyone can explore data freely without worrying about warehouse bills Benefits: - Up to 80% reduction in BI tool warehouse costs - Faster query performance (local compute is faster than warehouse round-trips) - Enables exploratory, iterative analysis without throttling - Still leverage warehouse for large queries when needed ## Who benefits Data teams: - Iterate freely on analyses without cost concerns - Work with AI agents that can dig deep without limitations - Faster performance for exploration and refinement Business users: - Explore data without needing to understand warehouse costs - Use self-service analytics safely and affordably Finance/platform teams: - Reduce data warehouse spend - Enable broader data access without cost explosion - Predictable costs even with increased usage ## Learn more ### Understanding the compute layer - Query execution model - How Count runs queries - DuckDB in Count - Local compute engine - Performance optimization - Writing efficient queries ### Using the Compute layer with Count Metrics - Count Metrics overview - Governed data models - Query performance & optimisations - When data is cached vs. live ### Query Performance and Management URL: https://learn.count.co/analytics-engine/compute-layer/query-performance >. Once you've written your queries in Count, you have control over how they execute and perform. This section covers optimizing database load, managing query execution, and troubleshooting issues. ## What you'll find here Query caching and scheduling - Store query results for a set duration to reduce database load, and schedule automatic refreshes during off-peak hours so your data is ready when teams need it. Manage queries and results - Control which queries execute and when, cancel running queries, and manage result size limits. Most queries run automatically, but you can take manual control when working with expensive queries or during high database load. Query troubleshooting - Diagnose inconsistencies between Count and other tools, understand non-deterministic query behavior, and resolve common query execution issues. ### Dynamic query compilation engine URL: https://learn.count.co/analytics-engine/compute-layer/dynamic-query-compilation-engine Literally magic. Count features a unique dynamic query compilation engine that enables unmatched flexibility in how you write and interact with SQL and no-code cells in the canvas. It is designed to harness the speed of modern cloud data warehouses while minimizing data movement and keeping your data secure. ## How does the dynamic query compilation engine work? At query runtime, Count dynamically compiles the SQL for each cell and sends it to the appropriate database, then renders the result. When two or more cells are joined together in the DAG, Count will include all SQL necessary to execute each cell - including the SQL from any parent cells. For example: - Cells a and b are SQL cells, cell b contains the SQL select * from a. - At runtime, Count sends the SQL for cell a to the database as-is (potentially adding a limit). - At runtime, Count generates the SQL for cell b which looks like with a as (), select * from a Because the query for each cell contains all of the necessary SQL, all queries can be executed in parallel. Due to this fact, it is common to see the results of some cells appear before their parents have finished executing, particularly if the results for the parent cell are larger. Remember, each cell is a compilation of CTEs - you can see the compiled SQL at any time and export it to your database. ## How does query compilation work for local cells? For any local cells in your DAG, query compilation and execution behaves slightly differently: - If a local cell references a parent cell from a data warehouse, the SQL for the parent cell is not compiled into the local cell. Rather, the parent cell is treated as if it is an external database table. - Local cells have to wait until their parent cells have finished executing before they can be executed, as local cells operate on cell results. ## What are the benefits of dynamic query compilation? By compiling SQL dynamically at runtime and relying on your underlying database for computation, Count enables the following: - Reusability - define a metric in one cell, then query that cell in downstream analysis. - Reactivity - changes flow through the DAG and cause downstream cells to update automatically. - Auto-lineage - Count builds the DAG for you by checking which tables you reference in your cells. - Control over data locality - you don't need to pull all of your database results into the canvas to benefit from cell referencing. - Performance - Count takes full advantage of the capabilities of your cloud data warehouse for scalability and query speed. - Write in native SQL - whatever your database, you can use your native SQL syntax to work in Count rather than learning a tool specific query language. ## When are cells executed? Cells are executed in response to several events. Here 'cell' could mean a SQL cell, visual cell, control cell etc. - A canvas is opened, and the cell is visible or referenced by a visible cell. - A report is opened, and the cell is in one of the report frames or referenced by one that is. - The input for a cell is edited. - The input of a parent of a cell is edited (this means that editing a single cell can cause multiple cells to execute). - A cell is duplicated or pasted into the canvas. - A new reference in a local cell is created to a cell that has not previously executed. - A new dynamic text reference is created to a cell that has not previously executed. - A frame is unhidden, and contains cells which have not previously executed. - The view is switched from a report to a canvas, which contains cells that have not previously executed. To disable automatic execution of cells that run on your data warehouse, select this option in the workspace settings or in the canvas query execution menu. ### DAG URL: https://learn.count.co/analytics-engine/compute-layer/dag What actually is DAG? (Directed Acyclic Graph) You'll see "DAG" everywhere in our docs - it stands for 'directed acyclic graph.' It feels like a bit of computer-science jargon, but it's a crucial concept which is important in data engineering, and becoming relevant for data analytics. Let's break it down: Directed - one cell influences another in a single direction only - and this influence must be in one direction only. Acyclic - no circular dependencies allowed. If cell A references cell B, then B can't reference A back (both would error). Graph - Just a fancy name for boxes connected by arrows. The DAG is represented in Count by the arrows which appear between cells. You don't have to think about it, Count will construct and manage the DAG automatically, but it's very helpful to be aware of the relationships between cells as those determine how cells execute in response to changes. ### Query Caching And Scheduling URL: https://learn.count.co/analytics-engine/compute-layer/query-caching-and-scheduling How to control when your queries run. Caching: Store query results in your canvas for a set duration (hourly, daily, etc.) to reduce database load and speed up access. Scheduling: Automatically refresh data during off-peak hours (like early morning) so reports are ready when teams need them. ## Enable caching in your workspace Caching must first be enabled in your workspace settings: Note: Info Query result caching is only available on paid plans. ## View canvas caching settings In the right sidebar, when no objects are selected the current caching settings for the canvas are displayed. To update these settings, click the Change button. Note: Info These settings are only accessible by analysts and above. ## Caching settings In the caching settings menu, there are three options for caching query results: Never cache results With this setting, whenever your canvas or report is opened, the queries for any visible cells will be sent to your database, ensuring the most up-to-date data possible. This option will result in the largest load on your database. Cache results for... With this setting, query results are saved for the specified duration. If the same query is run repeatedly within that time window, then cached results are returned. This option is often a reasonable trade-off between improving result freshness while reducing load on your database. If cells are edited or executed using the Run cell button, then queries are always re-run. Cache results indefinitely With this setting, queries will not run unless cells are edited or executed using the Run cell button. This option minimises database load, but may result in old data being displayed. ## Scheduling settings If a schedule is selected, Count will execute the cells in this canvas that are connected to databases periodically. These scheduled queries are always run, even if cached results are available, and the new results will update those in the cache. By default all canvas cells are executed, but it is possible to execute fewer cells by hiding or disabling cells, and choosing the appropriate option. Several simple schedules can be selected from the options here. For more custom schedules, choose the Custom option to enter a schedule in the form of a cron expression. For example, to schedule a run at 8AM on weekdays only, enter 0 8 * * 1-5 . Note that cron custom expressions are always based on the UTC timezone. ### Local Cells URL: https://learn.count.co/analytics-engine/compute-layer/local-cells Query data directly in your browser ## Local DuckDB cells In addition to running queries on your data warehouse, Count also ships with a local database built on DuckDB. If you choose to set a cell's data source to Local, the queries for that cell will be run in your browser. The diagram below shows how the different cell types are related: In summary: • Cells running on a data warehouse can query tables in that database, and other cells referencing the same database. • Local cells can query the results of any other cell, as well as any CSV files that have been uploaded to the canvas. ## When to use local cells Local cells are ideal for certain situations, including: • Joining multiple data sources - for example joining a CSV file to a database table, or joining results between databases. • Reducing load on your database - queries that run locally will not run on your database, and therefore not impact database query quotas or cost. • Performance - when performing an analysis or building a visual with many data points, it can be faster to first prototype locally then revert back to live data on your database for the full results. ## Create a local cell First, ensure that the Local database is selected in the Sources pane in the data bar: Secondly, create a cell using the control bar or keyboard shortcut as usual - you can confirm that the cell is local by checking the color of the cell name, the name of the source in the cell footer, or from the information in the right-hand sidebar. ## Querying other cells With a local cell selected, the options in the Data Bar will update to indicate which cells are available for querying. To query a cell just refer to it by name in the FROM clause of your select statement as usual. Note: Info The syntax for DuckDB is designed to be compatible with Postgres syntax. Under Tables you'll see: • CSV files - indicated with a different icon • Cells and visuals from your data warehouse - annotated with relevant color code Under Cells you'll see: • All local cells Once you have referred to a cell, you'll notice that the DAG connector line changes color to match the source cell. This is intended as a quick visual indicator that the referenced cell has potentially come from a different database. ## Move a cell/visual to the local database The cell controls in the right-hand sidebar show the database for the currently selected cell or visual. A cell can be made local by selecting Local from this menu. Note that the SQL syntax supported by DuckDB may be different from your data warehouse, so you may need to update the contents of the cell. Note: Info If you move a cell into the local database, any cells that reference it will return errors. ## Query result limits One concept to be aware of when using local cells is the risk of working with incomplete results. For example, suppose a canvas contained two cells: • Cell a - select price from transactions - this cell returns a 10,000 row preview of a result set that actually contains 100,000 rows. • Local cell b - select sum(price) from a - here the aggregation will not be correct, as the results from cell a are incomplete. By default, Count applies a 10,000 row limit to all queries executed on your database. If the results of a query exceed this limit, a notification will be displayed in the table footer: To increase this limit, you may click on the notification to attempt to download the full results set. An additional limit of 128MB for the total size of results also applies - if this limit is breached, then the notification becomes a warning: To remove this warning, you can try: • Selecting fewer columns • Adding an explicit limit to the query • Performing an aggregation or filter so that fewer rows are returned Note: Info Your workspace may have a higher limit than the 128MB default - if this is the case, the same rules apply, but with a higher limit. Any local cells that rely on incomplete results will also show a warning, even if those cells don't exceed any limits on their own: Read more about managing query result limits here. ## How does 'Copy compiled SQL' work for local cells? When compiling SQL, the behaviour for local cells is: • All parent local cells will have their queries compiled into CTEs as usual. • All parent cells from data warehouses will be referred to as if they were database tables - their queries will not be included as CTEs. All compiled SQL will be created in the DuckDB syntax. ## What are the memory limitations of local cells? Unlike queries on your data warehouse, Count does not limit the result size of local queries. However, the total memory usage of the local database is limited to approximately 3.4GB. During query execution Count will load the results of the cells being queried into the database and perform the query. Therefore any query has to obey the memory cap that includes: • The results of the query • The results of any parent cell • Any working memory the local database needs to perform the query If you encounter any out-of-memory errors, try: • Deleting cells that are no longer required for local queries • Performing more aggregation/filtering in data warehouse queries first before referencing those results in local cells • Avoid cross-joins and other constructs that produce a large number of rows in your local cells You can check your memory usage by executing the following query in a DuckDB cell: ## Troubleshoot Maximum call stack size exceeded If you see this error, it's probably because you're using a version of the Safari browser that applies memory limitations to background tasks in web pages (see more technical detail here). DuckDB runs in the background because otherwise long-running queries would cause the application to freeze. To fix this error, you can try: • Reducing the complexity of the query - for example, relying on fewer upstream cells or using fewer compound query features such as CTEs or UNIONs. This may help DuckDB to use less memory when executing your query. • Switching to a different browser - some other browsers have higher memory limits for background tasks, so may succeed in executing your query. ### Query Troubleshooting URL: https://learn.count.co/analytics-engine/compute-layer/query-troubleshooting A guide to resolving issues with queries ## SQL query results appear different between Count and another tool In performing a consistency check between Count and another tool, you may try running the same SQL query in both tools. Infrequently you may find the results of both queries appear different. The inconsistency is almost always the result of a subtlety of the SQL language or a difference in connection details. Below is a list of things to check before contacting Count support. ### Differences in client connection details If the user credentials attached to the Count connection and the other tool are different, please check that: - Both point to the same database/scope; modern data stacks often reproduce production schemas in a staging environment, so you may be accidentally querying different tables. - Both user credentials have the same level permissions for the tables being queried; this is particularly important if your database supports row level permissions. As Count supports querying of multiple database connections within the same canvas, please check that the cell refers to the same database instance being queried in the other tool. ### Differences due to execution time of the query The time at which the query is executed can lead to different results between Count and the other tool in two ways: At high load times your query may fail (in either tool), leading to an error for one query but not the other. Please interpret any errors returned and try performing both queries at a similar time. For transactional databases, tables may be appended to at any time. As a result, both query results may not exactly match. Consider creating a snapshot table within the database and performing consistency checks on that instead. ### Differences due to result representation Count currently doesn't support the representation of object and nested datatypes within the Count UI. Columns containing this type of data will appear as a JSON-stringified representation of the data. ### Differences due to non-deterministic queries A deterministic query returns the same results each time it's called. A non-deterministic query may return different results each time it's called. Some queries are obviously non-deterministic e.g. SELECT CURRENT_TIME, but others may be non-deterministic due to a subtlety of the implementation of the SQL language by your database. Please check the query executed, including any SQL used to generate views referenced in the query. Below is a list of common causes of non-deterministic queries. ### Non-deterministic functions - Time/date related functions may return different values in successive calls, and if used as a filter in your query, a different number of rows for your query. These functions include (but not limited to): - CURRENT_TIME, CURRENT_DATE, CURRENT_DATETIME, CURRENT_TIMESTAMP, or equivalent. - Some functions by definition return different values in successive calls, or are dependent on configurations in your database environment. These functions include (but not limited to): - GENERATE_UUID, SESSION_USER, RAND, or equivalent. - Some window functions are non-deterministic if they are navigational in nature when used without an ORDER BY clause within the OVER() clause. Some databases error when these functions are used without an ORDER BY clause, but may not check that the chosen ordering is appropriate. These functions include (but not limited to): - FIRST_VALUE, LAG, LAST_VALUE, LEAD, NTH_VALUE, PERCENTILE_CONT, PERCENTILE_DIST, CUME_DIST, RANK, NTILE, or equivalent. Non-determinism due to floating point accuracy Not all number types in databases can be stored with exact precision. This can lead to non-determinism when: - The number exceeds the maximum supported value of that data type. - Calculations using that magnify any floating point round-off errors, e.g. by subtracting two very similar floating point numbers. Please consult your database documentation to find the bounds and precision of the data types used. ### Non-determinism due to ordering The SQL standard does not order query results for SQL statements without an ORDER BY clause. This detail commonly manifests itself in two ways: - Executing the same SELECT * or SELECT column_name, ... query multiple times against a table may return results in a different order. This is to be expected. - All database queries in Count are by default limited to the first batch of 10,000 rows. Successive SELECT * or SELECT column_name, ... queries may return different batches of data. This is particularly important if these cells are referenced within local (DuckDB or Python) cells or visuals. When a Count cell is only showing a subset of the query result data, a label is shown in the bottom-right of the cell (or upper-right of a visual). Read more about how to handle these cases here. To work within this restriction and obtain the quantity of data you require, consider performing any ordering operations, aggregations and filters on the original database query before referencing in local cells. Please do contact Count support if this limit is still restricting your analysis. ### Manage Queries And Results URL: https://learn.count.co/analytics-engine/compute-layer/manage-queries-and-results Control when queries are executed, and how to access their results. Most of the time when using Count, it isn't necessary to monitor query execution - the appropriate queries will be submitted automatically based on your changes to cells and other canvas objects. In some cases it may be important to control exactly which queries are executed - for example, if the query is expensive or your database is expected to be under heavy load. Below you can read more about the query lifecycle in Count, and how to control queries and their results. ## Query lifecycle When a query begins executing in a Count cell or visual, the current state of the query is displayed in the output area of the cell: The stages are: • Connecting - your browser has asked for a query to be submitted. If other queries for the same connection are also waiting to be executed, the number of waiting queries will also be displayed. • Running query - Count has sent the query to your database, and is waiting for the results. The displayed execution time includes both the time spent running the query, and the time spent retrieving the results. • Compressing results - Count has received the result set for the query, and is compressing it. • Downloading results - your browser has been notified that the query results are ready, and has begun downloading them. Some of these steps may be skipped or display different information in the following cases: • Connecting - for local DuckDB or Python cells, this step also includes the time spent loading the database or Python instance, and waiting for upstream cells to finish executing. • Running query - this step may be skipped if cached results are available for the cell. • Compressing results - this step may be skipped if the query results are small. ## Run a new query When it is important to see the latest data for a cell, it is possible to tell Count to bypass any cache, and send a new SQL query to your database. If caching is enabled, the cached results will be updated at this point. • Clicking the Run cell button above any selected cells will execute those cells. (Note that choosing this option will also re-enable cell execution if it has been disabled previously). • Clicking the Re-run all cells button in the cell result table (see below) will re-execute all canvas cells. Please note that this action may result in submitting many queries to your databases. ## Prevent query execution If it is important to reduce load on your database, it is also possible to prevent cells from executing in response to changes: • Click the Disable cell execution button underneath the Run cell menu to prevent that cell executing automatically in the future. • Deselect the Execute cells automatically option in the design sidebar to prevent any cell from executing automatically. If a cell is prevented from executing automatically, it will show a message with an option to execute the query. If the cell is connected to a BigQuery connection, it will also show an estimate of the amount of data that will be processed by the query: ## Cancel running queries Count supports query cancellation for all database connections. Currently-executing queries can be viewed and cancelled from the settings pages for each connection. ## How query cancellation works The effectiveness of cancelling a query from Count may depend on the database connection used, and in which step the cancellation was requested: • Connecting - cancelling a query during this step should always succeed, as the query has not started execution yet. • Running query - cancellation from Count is not always guaranteed for some database types, though the cancellation request is always sent to your database. ## Cancel queries in a canvas If your role allows you to edit a canvas, the option to cancel all pending canvas queries will be available in the data menu: ## Cancel queries for a connection If your role allows you to edit a database connection, you are able to cancel all queries for that connection: • From the connection page, select See all from the queries section in the sidebar to view running queries. • Select one or more queries, then choose Cancel queries and confirm the cancellation When contacting Count support about a running query, please include the debug information about the query from the context menu: ## Manage query results By default, all cells in Count apply a limit of 10,000 rows in the SQL that is sent to your database to minimise the time spent transferring large result sets. (This limit is not applied to DuckDB cells.) This default behaviour can be changed from the Row limit settings in the Design sidebar: Selecting the Unlimited option will remove the 10,000 row limit from the SQL query, and Count will continue to fetch results until they are complete, or their uncompressed size reaches the limit configured for your workspace - typically at least several hundred megabytes. Note: Info It is strongly recommended to enable caching of results if using the Unlimited setting, to avoid frequent re-execution of long-running queries. • Server -> Browser - set this option to a number to limit the number of rows that are downloaded to your browser. Choosing Unlimited may result in high memory usage, and is typically not recommended unless there is a need to work locally for all downstream cells. Note: Tip If caching is disabled for this canvas, then all results are always downloaded regardless of this setting. ## Canvas cell results To see the currently-available query results for all cells in the canvas, click the status icon next to the cells pane in the data sidebar: This icon shows: - A green checkmark - no issues were detected with your query results - A warning triangle - if any of your cell results have expired, or are causing high memory usage. After clicking, the cell result table is opened: This table shows: - Name - the name of the cell, and name of the visual mark (if the visual has results from multiple marks). - Source - the data source that the results were derived from. - Size - the number of rows and columns in the result set. If a row download limit has been applied, this column shows both the number of rows available in the browser, and the number downloaded to Count's servers. If the query failed to execute, clicking the error will display the error message. - Bytes - the size of the uncompressed results that were extracted from the database in binary format. If a row download limit has been applied, this column shows both the size of file downloaded to the browser, and the size of the file on Count's servers. If the memory usage of these results is high (above 100MB), the size is highlighted in red. The memory usage of a result set may be much larger than the file size, once the results are loaded into memory. - Created - when these results were created - typically when Count finished extracting all of the results from the data source. - Expires - when the results are scheduled to be removed from Count's servers. Once results have expired, they can no longer be referenced by DuckDB on the server, so in this case any downstream DuckDB cells will begin to run in the browser. If results have expired, the expiration time is highlighted in red. - Query duration - how long the query took to execute. - Extract duration - how long it took to extract the results from the data source. In some cases this duration is included in the query duration, and so is not shown. Hovering over any table row presents options to navigate to the cell, or re-run the cell: ## Profile DuckDB performance If you find your DuckDB cells are running slowly, and the duration listed in the footer of the cell is high, you can profile the cell to pinpoint performance issues. Select Profile query performance from the sidebar, and a new query will be executed for that cell with performance tracing enabled: In this view you'll see: - Query plan - the steps taken by DuckDB to execute your query, from inputs at the bottom to outputs at the top. Long-running steps or large step results are highlighted in orange and red colours. - Compiled SQL - the SQL that was actually executed by DuckDB. It includes any upstream cells that were compiled into the query, and any compiled Jinja expressions. - Performance suggestions - if AI is enabled for your workspace, on the right you'll see some automated suggestions for improving query performance based on the query plan and executed SQL. - Download profile - download the query plan in JSON format to explore yourself, or in third-party tools - for example, this open source DuckDB query plan viewer. ### DuckDB on the server URL: https://learn.count.co/analytics-engine/compute-layer/duckdb-on-the-server >- When cells return a large results set, by default Count will only return the first 10,000 rows of the results to your browser. When this happens, the footer of the cell will contain some information about the full result set: You can choose to download all of the results, in which case downstream DuckDB cells will run in your browser. Otherwise, any downstream DuckDB cells will be executed on Count's servers rather than in your browser. When running on the server: • The full results of any upstream cells are always available • DuckDB may have access to more working memory than it does when running in a browser • Queries may fail if they use too much memory, or attempt to access files on the local filesystem The versions of DuckDB in your browser and on Count's servers are the same, so you shouldn't notice any difference when running queries. Note: Info You may also see DuckDB cells running on the server when your local DuckDB database is nearing its memory limit. ## Query limits When using DuckDB on the server, your queries are executed in isolated virtual machines (VMs). These VMs execute one query at a time, and have limits placed upon them which may depend on your subscription plan: • Total available RAM - this is the total amount of RAM that the VM can use, which includes the space it requires to load any parent cells, execute the query, and stream the query results out of DuckDB. The VM uses a minimal operating system, which adds approximately 100-150MB of RAM overhead while running the query. • Maximum result size - Count will stop streaming the results out of DuckDB once the total uncompressed size of the results (in Arrow format) reaches the limit configured for your workspace. This limit is typically half of the RAM size allocated to the VM. • Total query duration - queries are terminated after they have been running for 1 hour. • Maximum query concurrency - each workspace can execute up to 100 concurrent DuckDB queries on the server. (DuckDB queries in the browser have no concurrency limits.) Why is the maximum result size less than the total available RAM? When executing queries, the VM needs memory space to load its operating system and allocate memory during the processing of the query. (Results are always streamed out of the VM, so their impact on memory usage is minimal.) Additionally, it is common for queries to reference multiple parent cells, which requires loading multiple parent result sets into VM memory. For these reasons, Count uses a default factor of 2 between the VM RAM size, and the maximum query result size. If you find that this default is not appropriate for your workload, please contact Count support. ## Cells overview URL: https://learn.count.co/analytics-engine/cells-overview Cells are the building blocks of your canvas. ## What are cells? Cells are how you query data sources and view results in Count - every cell has an input (some form of query) and an output (a table of results). While there are many types that look and function differently, under the hood every cell represents either a SQL select statement or Python expression that returns a table. ### Cell types - SQL cell - type SQL directly into the cell, using the syntax for your database (or Jinja). - Visual cell- build pivot tables or charts without code by selecting columns from your database or other cells. - Control cell- create an interactive widget that provides input parameters for other cells. - CSV cell - upload CSV files to the canvas to use as a data source for other cells. - Python cell - type Python code directly into the cell. ### How do cells work? Each cell is a query Each cell is a query that is sent either to your database, a DuckDB database hosted by Count , or Python. Count's dynamic query compilation engine compiles SQL at runtime. Cells reference and build upon one another Because cells can reference a database or another cell, they can be chained together into a linear or branching analysis. This allows you to break complex problems into easier to solve chunks. Count automatically connects related cells to one another to make data flows easy to follow - this structure is called the DAG, and is indicated in the canvas with arrows between cells. Cells are reactive Any change in a cell will automatically flow through to all downstream cells. This makes updating your analysis a seamless process, and ensures that all cell results are kept in-sync with one another. SQL cells are CTEs Under the hood, each SQL cell is a common table expression (CTE). You can view this SQL at any time by right clicking the cell and choosing Copy as -> Copy as SQL. Because Count uses the syntax of your underlying database, you can port this SQL out of Count and into your database or dbt at any time. Count's dynamic query compilation engine makes all this goodness possible. Check it out in detail here. ## Working with cells ### Creating cells There are various ways to create cells in the canvas: - Clicking the control bar at the bottom of the canvas, or using keyboard shortcuts. - With the buttons that appear when you hover over the edge of any existing cell. This will create a new visual, SQL or Python cell that is pre-configured to reference the starting cell. - Dragging a table from the data bar into the canvas to create a SQL cell. - Dragging a column from the data bar into the canvas to create a visual cell. - Adding a dbt model from the data bar. ### Naming cells When you create a cell it will be given a default name. We strongly advise you to rename the cell to help remind yourself, and others, of what each cell represents. This is the name you will use to reference the cell in any code you write. Don't worry about changing a cell's name later - if you ever change a cell's name, you'll have the option to update the references in all downstream cells. ### Cell context menu The cell context menu contains additional cell-specific options for formatting, copying, selecting, and downloading data from cells. Right-click anywhere on the cell to open it. ### Visual and low-code cells URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells Making data pretty since 1160 BC*. Visual cells are where you create visualizations in Count. They can be built from other cells, or directly from database tables. ## Create a visual cell Check out the Visualization Overview to see how to create a visual cell, and take a look at our document on adding a table. ### See the output table of a visual In any visual, you can toggle between the visual and the table of results. This allows you to see the row-level detail of your visual. ### Querying a visual You can query a visualization to continue your analysis (think: pivot your data, then query the resulting pivot table). Reference a visual cell by: - building a SQL cell that references the visual cell name in the FROM statement, or - selecting one of the Reference cell shortcuts near the edge of the selected visual Visuals that contain more than one mark have multiple queries (and therefore output tables) associated with them — one per mark. The output table that is referenced by another cell is that returned by the lowest non-empty mark. ### Execute visual queries locally By default, your visuals will be executed as queries on your data warehouse. If you would prefer to instead perform these queries locally, you may select the Local database option from the cell controls in the right-hand sidebar. If the visual is built directly from a database table, then this option will not be possible. In this case you should first create a cell that references the database table, then ensure the visual references that cell. Low-code cells provide a quick and easy way to query data without the use of SQL or Python. They combine many of the controls of visual cells with the single-table output of a SQL cell. ## Creating a low-code cell Create a low-code cell by either: - Using the X keyboard shortcut to place a new cell - Selecting the Low-code cell option from the control bar - Clicking on the + icon that appears when the cell is selected and then selecting Low-code cell ### How low-code cells work Count’s low-code cells make it easy for anyone to explore and analyze data—no SQL needed. Low-code cells output a single table just like SQL cells, but their queries are controlled via a UI similar to that for visuals. You can chain low-code cells to each other or any other cell type, and they will update automatically when any of their dependencies change. First select the base table you want to query, and then either: - Drag the columns you'd like to explore into the Columns section - Click on each column to add You can add filters by dragging columns into the Filters section. You can add columns from multiple tables or cells by using low-code joins. #### Visualization overview URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/visualization-overview How visualizations work in Count. To visualize data in Count, you’ll need to create a visual cell. There are several ways to do this: - Ask the AI Agent to create a visualisation for you - check out some ideas and reusable prompts here. - Toolbar: Click the Visual button in the canvas toolbar, then click on the canvas to place it. - Keyboard shortcut: Press V, then click on the canvas to place it. - From an existing cell: Click the + shortcut near the edge of a selected cell and choose Visual. - From the data sidebar: Drag a column directly into the canvas. The last two methods (using the + shortcut or dragging from the sidebar) have the advantage of automatically setting the source for your visual. Once a visual cell has been created, you can build it in two main ways: - Templated visuals << the quickest way to start. - Custom visuals << provides more options and flexibility. Dynamic text is another method to present single live data values in the canvas. You can use it in text boxes, sticky notes, or shapes. This allows you to blend live data into your notes, titles or comments so whatever you write stays current. If you would like to learn more about creating visualisations in Count, the following tutorial videos provide an overview: Part 1: Getting started with visuals: Learn to create customizable data visualizations through visual cells, including charts, tables, and pivot tables, with data governance and formatting tips. [Video: Getting Started with Visuals] Part 2: Advanced visualizations: how to go beyond templates in Count. Switch to the Custom tab to layer marks, use facets/subplots, pivot measures, and add table calculations. [Video: Advanced Visualizations] [object Object],[object Object] #### Templated visuals URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/templated-visuals The quickest way to visualize your data. Once you've created a visual cell, templated visuals are the quickest way to start constructing a visual and exploring your data. ## Create a templated visual • Create a visual cell — see here for all ways to create a visual cell. • Select a template — choose a template by clicking the template preview image next to Type. Available categories are: Pivot table, Card, Column, Bar, Line, Area, Scatter, Hierarchy, Flow and Statistics. • Select the data source - Pick the source you want to build your visual from the dropdown in the design panel on the right. This can be: • Choose columns - Drag columns from the sidebar into the available slots for your chosen template.Once placed, you can configure each column using the ellipses (...) menu: • Filter the data — read more about how to filter the data displayed in your visual here. • Format the visual — read more about formatting visuals here. Note: Info Tip: Clicking on an axis of your visual will sort the data by that value ##### Area Chart URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/templated-visuals/area-chart Area Chart Area charts extend line charts by filling the space beneath the lines, making it easier to see volume or cumulative totals. Area charts work well for highlighting the magnitude of change over time or comparing contributions between series. ## Template options 1. Simple area → fills under one or more lines to show absolute values. 2. Stacked area → layers series on top of each other to show combined totals. 3. 100% stacked area → normalizes to percentages, showing relative contributions across categories. ## Mapping options • X → Dimension for the horizontal axis (often time or ordered categories). • Y → Measure for the vertical axis (height of area). • Color → Splits the area into series, enabling stacked or 100% stacked variations. • Label → Annotates points or areas with text. ## Tips 1. Use area charts when you want to emphasize totals or filled volume, and line charts when clarity of trend is more important. 2. Too many series can make overlapping areas hard to interpret — limit to 4–5 for clarity. 3. Transparency helps distinguish overlapping areas in the simple variant. ##### Flow Chart URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/templated-visuals/flow-chart Flow Chart aka Sankey diagram Flow charts show how values move through stages or categories. • Sankey displays flows between multiple levels. • Funnel shows sequential drop-offs through a process. ## Sankey chart A Sankey chart shows how values flow across multiple levels, with line thickness representing size. Data shape - your data must be in wide format: one column per level, plus a numeric column for the flow size. Each row describes one path through the levels. ### Mapping options • Level → Add each level column in order (e.g. Level1Channel, Level2Action, Level3Outcome). • Weight → Numeric column for flow size (e.g. Value). Tips • At least two Level columns are required; more levels extend the flow. • If your data has levels stacked in a single column (long format), reshape it so each stage gets its own column. ## Funnel chart A Funnel chart shows how values drop off across sequential stages. Data shape - your data should be in long format: one column for the stage name and one column for the measure. ### Mapping options • X → Measure column for stage size (e.g. Value). • Y → Dimension column for stage names (e.g. Stage). • Color → Dimension to split each stage into sub-groups. • Label → Annotates stages with text. Tips • Works best with fewer than 6–7 stages. • Values should decrease progressively—funnels are less clear if the sequence jumps up and down. • Adding Color can highlight different groups moving through the same steps. ##### Hierarchy Chart URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/templated-visuals/hierarchy-chart Hierarchy Chart Hierarchy charts visualize proportions within categories, making it easy to compare part-to-whole relationships. • Treemaps use nested rectangles sized by value. • Packed bubbles use circles sized by value. ## Treemap ### Mapping options (Treemap) • Color → Dimension or measure for rectangle shading. • Size → Measure to define rectangle area. • Label → Adds text to each rectangle. • Detail → Adds extra breakdown inside each rectangle. ## Packed bubbles ### Mapping options (Packed bubbles) • Color → Dimension or measure for bubble shading. • Size → Measure to define bubble size. • Label (optional) → Annotates each bubble with text. • Detail (optional) → Adds extra grouping dimension. Tips • Both visuals are best for part-to-whole comparisons. • Use Size for your main quantitative field. • Detail lets you drill into a second dimension. • Avoid too many small values—they can create clutter and make shapes too small to interpret. • Use Color sparingly: too many categories can overwhelm the chart. ##### Line Chart URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/templated-visuals/line-chart Line Chart Line charts connect data points with lines, making them useful for showing trends, changes, or comparisons over time. Line charts can also be combined with bars for dual-axis visuals that highlight relationships between two measures. ## Template options 1. Simple line → plots one or more series across a continuous axis. 2. Combo (bar + line) → overlays a line series on top of bars to compare different measures in the same chart. ## Mapping options ### For line charts • X → Dimension for the horizontal axis (often time or ordered categories). • Y → Measure for the vertical axis (line height). • Color → Splits lines into series. • Label → Annotates points with text. ### For combo (bar + line) • Cols → Dimension for the horizontal axis (shared by both bar and line). • Bar • Line ## Tips - Line charts work best with continuous or ordered categories (e.g. time, sequence, ranking). - Avoid too many series (over 5–6) to keep lines readable. - Use combo charts when you want to highlight the relationship between two measures, such as volume (bars) and rate (line). ##### Statistics Chart URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/templated-visuals/statistics-chart Statistics Chart The Statistics chart shows the distribution of a numeric field. Data values are automatically grouped into bins, and the count of records in each bin is plotted as a line. ## Mapping options • X → Numeric field to bin into ranges. • Y → Count (auto-calculated from the numeric field). • Color → Dimension to split the distribution into multiple lines. ## Tip • Try adjusting bin size to see different levels of detail ##### Bar And Column Charts URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/templated-visuals/bar-and-column-charts Bar And Column Charts Bar and column charts display values across categories using rectangular bars. They make it easy to compare magnitudes between groups, see rankings, or show parts of a whole when stacked. The only difference is orientation: bar charts run horizontally, while column charts run vertically. ## Template options 1. Simple bar → shows one measure per category. 2. Stacked bar → layers multiple measures or series within each category. 3. 100% stacked bar → normalizes values to percentages, comparing contribution across categories. ## Mapping options • X → Dimension for category values (column variant) or measure for length (bar variant). • Y → Measure for column height (column variant) or dimension for categories (bar variant). • Color → Splits each bar into series, enabling stacked or 100% stacked variations. • Label → Annotates each bar or segment with text. ## Tips 1. Use bars for ranked comparisons, columns for timelines or sequential categories, and stacked versions for part-to-whole analysis. 2. Keep category labels short, or rotate them for readability. You could also flip the visual if you decide to switch between bar and column charts. 3. Use stacked bars to show contributions, but limit the number of series (5–6 max) for clarity. 4. Choose 100% stacked when the focus is on proportions instead of absolute values. ## Troubleshoot How do I customize labels on a barchart? ## Customizing labels on barcharts When customising labels on a chart beyond a single field, you have two main options: 1. using calculated fields in a label 2. using text marks over the bar chart ### Option 1: using calculated fields in a label ### Option 2: using text marks over the bar chart How do I show multiple values on a barchart? ## Showing multiple values on a barchart Bar charts can display multiple values at once, including both total values (at the top) and percentages (within bars) simultaneously, giving users both absolute numbers and relative proportions in one clear visualization. ### Adding in multiple values - Start with stacked bars: Select data → stacked bar visualization → switch from 'template' to 'custom' - Add the percentage layer: Split bars using the color field, add values to the label field, click 3 dots → normalize data to show percentages of each segment - Add the totals layer: Duplicate the bar mark → change type to "text", remove the color-splitting metric, remove normalization to show total values This will result in a bar chart with percentage breakdowns inside each bar and total values displayed at the top - perfect for showing both the big picture and the details simultaneously. ##### Card Chart URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/templated-visuals/card-chart Card Chart Card charts display a single key value in a clear, prominent way. They are best used for KPIs, headline numbers, or summary metrics you want to highlight on a canvas. ## Template options • Simple card → shows one measure as a large number. ## Mapping options • Text → The measure or field to display in the card. ## Tips 1. Use cards for metrics that need to stand out, such as revenue, active users, or conversion rate. 2. If you want to customise further, you can either click the Custom tab for additional options, or adjust the Style → Label settings to change font, size, color, and other formatting. 3. To add text into a card, switch to the Custom tab and add a Text Mark, adding your text into Text, and changing the y position (e.g. to 2) in Type -> Subplot to move your text below the data. 4. If you want to include a data value within text (e.g. in a sentence), you can use Dynamic Text for this. 5. Cards work well when combined with supporting charts to give context to the value. ##### Pivot Table URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/templated-visuals/pivot-table Pivot your data Pivot tables summarise data into a grid, letting you arrange dimensions into rows and columns with measures aggregated into values. They’re useful for breaking down data by multiple categories, spotting patterns, or comparing across groups. ## Template options 1. Basic pivot table → displays rows, columns, and aggregated values. 2. Pivot table with color → adds conditional formatting to highlight differences or ranges in the data. ## Mapping options • Rows → Dimension(s) to group along the vertical axis. Multiple fields can also be added here, with order controlling the hierarchy. • Cols → Dimension(s) to group along the horizontal axis. Multiple fields can also be added here, with order controlling the hierarchy. • Values → Measures to aggregate (sum, count, average, etc.). • Color → Applies conditional formatting to values. ## Pivot table versus table ### Pivot Visual • Great for summarising data • Easy grouping across rows/columns • Less flexible around sorting/filtering • Cannot export pivots in their pivot format ### Table Cell • Great for quickly visualising your data • Easy sorting and filtering • Can work with aggregated data from the SQL cell • Good for exporting the CSV in the same format ## Troubleshoot Why can't I sort by column in my Pivot Table? ## Sorting the pivot table If you have created a Pivot Table to display your data, but when you try to sort your data by column it doesn't appear to work as you expected, it may be that a standard table is more suitable for your use case. This video explains the difference between these two formats. Note: Embedded Content Embedded content: https://www.loom.com/embed/dba6eb015e5843d48c987ae3acdfd14c How do I add a color scale to a single column in a Pivot Table? ## Adding colour scale to one column - Switch to Custom tab for your pivot table - Change Marks -> Type from Automatic to Square - Add your column to apply the scale to into Color and Label - In Color, navigate to Display and alter the color palette as preferred - To add additional columns with a color scale, add/duplicate your Mark, move the x-axis Subplot setting up by 1 (this determines it's position), and modify the Label and Color field to your new data point, editing the scale palette as earlier outlined. Note: Embedded Content Embedded content: https://www.loom.com/embed/8fdb8f4380ed4177b744d6a41a8d3bd2 How do I add a totals row to a Pivot Table? ## Adding row totals - Switch to Custom tab for your pivot table - Move your row facet field to the y-value channel - Add the Measure Values into Text - Duplicate the Text Mark (to create another Mark) - Change your y-value to Measure Names - this will add a summary in. ##### Scatter Chart URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/templated-visuals/scatter-chart Scatter Chart Scatter charts plot values along two numeric axes, making it easy to see relationships, clusters, or outliers. A bubble scatter variation adds a third measure by changing the size of each point. ### Template options • Simple scatter → plots points by X and Y values. • Bubble scatter → plots points by X and Y, with size mapped to a third measure. ### Mapping options • X → Measure for the horizontal axis. • Y → Measure for the vertical axis. • Color → Dimension to split points by series. • Size (bubble variant only) → Measure for bubble size. • Label → Annotates each point with text. ### Tips • Scatter charts work best when both axes use continuous measures. • Use Color to highlight group differences, but avoid too many categories (over 6–7 colors can be hard to read). • For bubbles, make sure the size measure has a meaningful range to suit your data, you can adjust the range limits in the Display options for that field. #### Custom visuals URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/custom-visuals For full power and flexibility. Custom visuals allow much more control over the exact layout and presentation of a visual. Tip: Starting with a templated visual is a quick way to get set up, and converting it to a custom visual lets you fine-tune the details. - Create a visual cell — See here for all ways to create a visual cell. You can also start with a templated visual and then convert it to a custom visual (from step 2 onwards). - Select custom visual — select the Custom option from the visual controls: - Select the data source — choose the source you want to build your visual from: a view from a catalog, a table from a database, or another cell. You can join other tables or cells using low-code joins. - Construct the visual — custom visuals are very powerful and it is possible to create almost any kind of visual - the following pages go into more detail on specific features: - Marks - Facet - Subplots - Filter the data — read more about how to filter the data displayed in your visual here. - Format the visual - read more about formatting visuals here. ##### Facet URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/custom-visuals/facet Split visuals into separate rows and cols. Faceting allows you to repeat a visual across all values of a column, and provide a way to create hierarchical axes. For example, the following chart is grouping the Total Sales by Region (Central, East, etc.). This is achieved by putting Region in the Rows field under Facet. In this example, the Region column has also been added to the Color channel to help visually distinguish the data for each region. - Facets group the data into distinct partitions, and repeat the subplot(s) for each partition - Facets can contain hierarchies with up to 8 levels - Understand the difference and when to use facets versus subplots in our visualization guide. ## Layouts for tables and heatmaps Another common way to use facet is to create tables or cohort charts. The following example uses the Rows to show two columns in the data, and the Cols to generate the columns in the table. In this case, the Rows aren't hierarchies but by placing them under Facet as Rows we can have as many columns as we want. ## Layouts for repeated marks A third way to use facet is if you want to repeat a mark across several different categories. For example, in this chart a track's danceability and energy is repeated across each individual artist. This is achieved by putting main_artist in the Rows field under Facet. ## Independent scales per facet When your faceted charts have very different value ranges, you can set each facet to use its own scale instead of sharing one scale across all facets. To enable this: click the three dots on the axis you want to adjust, then toggle on Independent scales per facet ##### Marks URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/custom-visuals/marks The building blocks of visuals. Marks are the atomic building blocks of visuals. They provide primitive shapes whose properties — such as position, size and color — are driven by data. The marks in a visual can be controlled in the Design sidebar on the right of the UI. ## Mark types Count supports the following mark types: - Area - Bar - Circle - Line - Sankey - Square - Text - Tick Map cells support - Circle - Geoshape - Text You can select the desired mark type by clicking on the dropdown next to type. Or, alternatively, if you choose Automatic, Count will select the most appropriate mark based on the data in the visual. (This is the default.) ## Channels Marks can be customised by controlling the various channels attached to them either dynamically from a column of values, or from a single, static value. A list of columns will show in the side bar. You can drag these to the desired property in the mark. Or, for some channels like color and size, you can adjust the static value. - X, Y The position of the mark. - Color The color of the mark. - Size The size of the mark. - Path The order in which marks are connected to form a line or area (for example, connecting time-based points in sequence). Only available for area and line marks. - Text/Label The column driving the text (for text) or label (for other mark types). - Detail Additional fields to group the data by (these do not appear explicitly in the visual but are shown in the tooltip). ## Applying functions By clicking the ellipses beside a channel name, the function applied to the column can be changed (aggregation or, for date columns, date grouping): ## Secondary X and Y axes By default, marks are plotted against an x-axis on the bottom of the visual, and a y-axis on the left. In order to use an x-axis on the top or y-axis on the right of the visual: - Click the ellipsis next to the channel - Select the Display tab - Select Secondary axis ## Multiple marks A visual can contain an arbitrary number of marks, with each mark layered on top of the last. In the example below, the line mark is layered on top of the bar mark: To see how to make a Bar and Line chart, check out this guide: Every Visual Under The Sun ## Mark options The mark menu, accessed by selecting the ellipses beside the mark type, contains some additional controls for the mark including: - Assigning the mark to a subplot. (Read more about subplots here.) - Show/hide mark (shown by default) - Show/hide tooltip (shown by default) - Stacking (by default enabled for area and bar marks, disabled for others) - Toggle to show/hide in the marks legend - Name (as it will appear in the marks legend) ## Deleting a mark To delete a mark you can click the -next to the mark. (Note that all visuals must contain at least one mark; the last mark cannot be deleted.) ##### Subplot URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/custom-visuals/subplot When one isn't enough. When comparing multiple measures it's sometimes helpful to make use of subplots. These create new axes onto which marks can be mapped. The number of subplots in the visual will change to as necessary accommodate all marks. ## Structure The large-scale structure of a visual is controlled by Subplots, Facets and Secondary Axes ## Subplots - In order to change the subplot a given mark is on, click on the ellipsis next to the mark type to bring up the mark controls: - Subplots allow multiple marks to be plotted against a common axis in one direction, with separate scales in the other - Count supports up to 64 (8 x 8) subplots in a visual ## Butterfly chart In the following example of a butterfly chart we use two x-axes to show two different metrics. We use subplots and reverse the scale of one mark to achieve this. These x-axes share the same y-axis. #### Formatting a visual URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/formatting-a-visual How to format your visual exactly the way you want. Once you’ve created a visual, you can adjust how your data is displayed. Formatting options control the appearance and readability of your chart. ## Axes Control how data is presented along your chart axes. - Edit axis – Change the measure or dimension used for an axis. - Format axis – Adjust scale, tick marks, and number formatting. - Spacing – Add or reduce padding around axis labels. - Rotation – Rotate labels for readability. - Show/Hide axis – Toggle an axis on or off. ## Labels - Add and format labels to show exact values. ## Legend - Format, move, or hide the legend. ## Title - Add and style a title for a visualization. ## Tooltips - Add, remove, or customize tooltip data. ## Style - Format the chart, rather than the data (background, gridlines, borders, fonts, text sizes). ## Layout and sizing These options affect the placement, layout, and overall control of a visual in your canvas: - Flip visual: Swap X and Y axes. - Fill available space: Resize the chart to fill the visual cell. - Resize to fit: Adjust the visual cell size to neatly fit the chart. - Show data: Display the underlying data table. - Reset visual: Revert the chart to a blank state. - Scroll anchor position: Set where the chart scrolls from Explore our visualization guide to take your visual to the next level. ##### Tooltips URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/formatting-a-visual/tooltips Show more data without cluttering your visualizations. By default, any columns mapped to any field of the visual will contribute values to the tooltip which appears when hovering over the visual. ## Add data to tooltips To add additional data categories to the tooltips click on the Custom tab of the Design bar, and under the Marks section add columns to the Detail mark type. ## Remove data from tooltips - To remove/show a specific field from a tooltip: - Click the ellipses (...) menu next to the field you want to hide. - Click to hide or show tooltip. - To hide/show tooltips entirely for a mark: - Click the ellipses (...) menu next to the mark type. - Click to hide or show tooltip. ##### Secondary axis URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/formatting-a-visual/secondary-axis Secondary axes can be used to display two (or more) marks on top of each other, but projected against different scales ## Adding a secondary axis - Click on the 3 dots by the axis you want to move - Click on the Display tab - Toggle on Use secondary axis ##### Layout and sizing URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/formatting-a-visual/layout-and-sizing Flip, shrink, reset - options to transform your visual ## Quick options (icon set) These options affect the placement, layout, and overall control of a visual in your canvas: - Flip visual: Swap X and Y axes. - Fill available space: Automatically resize the chart to fill the visual cell. The chart will continue resizing as the cell size changes. - Toggle back to Fixed sizing using the same icon to keep the chart size static. - Resize to fit: Adjust the visual cell size to neatly fit the chart. - Show data: Display the underlying data table. Click again to return to the visual. - Reset visual: Revert the chart to a blank state. ## Additional options (... menu) - Scroll anchor position: Set where the chart scrolls from (top, bottom, left, or right). - By default, time runs left to right. New data may be hidden on the right; anchoring scroll to the right (or bottom) ensures the newest data stays visible. - Sizing: Provides more granular control over the chart size within the cell via dropdown options. - Legend: Toggle the chart legend on or off, and edit the legend title when enabled. See Legends for full details on customizing them. ##### Axes URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/formatting-a-visual/axes This guide will show you how to change the format and presentation of your chart axes. ## Axis formatting You can access the axis format menu in two ways: - From the design panel: Select the ellipses next to the field of the axis you would like to edit, then select the Displayto open the axis options. - From the visual: You can right-click directly on the axis in the visual and select Edit axis. From the Display menu you can: - Change the axis title - Sort the axis - Adjust the axis scaling (e.g. linear, logarithmic etc.) - Adjust the axis range - Reverse the axis - Round axis limits - Use a secondary axis - Format the axis labels By default the axis will be set to 'continuous' on a linear scale with rounded limits. ## Discrete vs Continuous Axis A discrete axis displays separate, distinct categories, ideal for categorical data like product types. In contrast, a continuous axis represents a seamless range of values, such as time or temperature, showing data in a flowing sequence. Use discrete for individual groups and continuous for data measured over intervals. ## Axis spacing For categorical axes, find the resizer by moving your mouse between the axis labels until a boundary is highlighted and the cursor changes to a resizer. Then just click and drag to change the spacing between labels: If you want to try and fit all of the data in your chart into your visual cell, you can also use the 'Fill available space' icon in the design bar. See Layout and sizing for information on all the icons in this menu: ## Rotate axis labels To rotate axis labels, right-click the axis and select Rotate labels. Labels can only be rotated for discrete mappings. ## Hiding/Unhiding an axis To hide an axis, right-click on the axis and select Hide axis. To unhide an axis, right-click anywhere on the visual cell and select Unhide all axes. ## Shortcut to sort axis Click directly on the axis to sort the data in its natural order for that data type. Click again to reverse the sort. Full sort options are available in the Display tab. ##### Legends URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/formatting-a-visual/legends Legends appear by default if there are any columns added to the Color or Size fields. A legend acts as a key that explains the symbols, colors, or patterns in your chart (similar to a map key) helping readers understand what each element represents. Legends can be customized in the following ways: - Hide/show the legend - Hide/show specific fields and marks in the legend - Change the title of the legend, and the display name of each mark - Change the position of the legend - Change the font style of the legend title and display names ## Hide/show the legend - To hide or show the legend click the ellipses (...) for the visual (which is just below the Custom tab) and toggle to show or hide it. - When toggled on, you can also change the title of your legend. It is also possible to hide a legend by right-clicking directly on a legend title in the canvas and selecting Hide legend ## Hide/show specific fields and marks in the legend To show/hide specific marks in the legend: - Select the ellipses (...)menu next to the mark type. - Toggle on or off Show marks in legend - Edit the display name for the mark in the legend if required To show/hide specific fields in the legend: - Navigate to the field you want to unhide the legend for. - Click the ellipses (...)menu. - Go to Display and enable the legend. You can also access the above options by right-clicking on a category in the legend itself and selecting Edit legend... ## Setting legend position - Right-click on the legend title. - Select a position from the Legend position menu. ## Font style of legends Refer to the Style section for formatting the font style within legends. ##### Title URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/formatting-a-visual/title You can add a title to a visualization from the top of the design panel. You can add a title to a visualization from the top of the design panel. Open the ellipses (...) menu in the Title style section to adjust: - Font - Color - Style (e.g., bold, italic) - Size The title is displayed in the top-left corner of the visual cell. ##### Style URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/formatting-a-visual/style Create a consistent visual language for your visualizations In the visual builder, you'll notice a Style section which is split into 3 tabs. This is where you can manage the styling of the visual itself (not the data). ## Tab 1: Text Styling With this menu, you can: - Customize the font color, size, and style for the entire visual. Settings applied under Default will affect all categories. - Apply unique text styles to Labels, Legends, and Axes. Any changes made to individual categories will override the default settings. ## Tab 2: Grid Styling With this menu you can customize: - The grid colors of the graph - The divider lines (Divider) - Tick marks (size, style and color) - Spines and Grids (size, style, and color) Moreover, you can adjust some of these for all axes (x and y) or just one or the other. Clicking on 'Replace mixed content' in the 'X and Y' view allows you to overwrite the individual X and Y settings. ## Tab 3: Sheet Styling With this menu you can customize: - The background colors of the graph (Sheet + Pane) - The Axis colors on the graph - The Rows colors on the graph - The Columns colors on the graph You can revert all style settings to their defaults by clicking the arrow icon at the top of the style options panel. ##### Label URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/formatting-a-visual/label Adding and formatting labels To add and format data labels in your chart: - Add a Label: Drag a column into the Label field of the design bar (from either the Template or Custom tab). - Format the Label: Click the ellipsis (…) next to the Label field, go to the Display tab, choose a Type, and update the relevant fields for that data type. You can also use a Text Mark to add a label to your chart. ## Troubleshoot How do I customize labels on a barchart? ## Customizing labels on barcharts When customising labels on a chart beyond a single field, you have two main options: 1. using calculated fields in a label 2. using text marks over the bar chart ### Option 1: using calculated fields in a label ### Option 2: using text marks over the bar chart #### Filter data in a visual URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/filter-data-in-a-visual Control the data that is visualized with powerful filters. If you want to include or exclude certain values in your visual, use the Filters channel in the design bar: - Add a filter: drag the column you want to filter into the Filters channel (in this example, Category). - Configure the filter: click the ellipsis beside the column name to set your filter conditions. ## Advanced filters - To apply more complex logic, select Create advanced filter from the filter options menu. - Here you can add multiple criteria, chained with AND or OR. - Click the ellipsis for options to group criteria together for further control. ## Dynamic filters You can also connect filters to control cells, allowing you (or other canvas users) to change the visual dynamically. #### Totals and subtotals URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/totals-and-subtotals Add totals and subtotals to pivots and charts. Totals and subtotals add summary rows and columns to your visuals — giving you grand totals across the whole result, and subtotals at each level of a row or column hierarchy. In Count, totals are recomputed from the underlying rows, not summed from the cells you can see. This means that non-additive aggregations such as averages, distinct counts, medians and percentiles produce a correct value at every level, not a misleading "sum of averages". ## Getting started Totals are configured per-visual from the right-hand sidebar of any supported visual cell. To turn totals on or off: - Select the visual cell. - Open the Visual options panel in the right sidebar. - Find the Totals control. - Click the eye icon to show or hide all totals at once. ## Options The Totals control exposes four independent toggles. Rows and columns are configured separately, and grand totals are configured separately from subtotals. - Rows → Grand Totals — a single column on the right aggregating across all columns. - Rows → Totals — a subtotal column at every level above the leaf in a row hierarchy. For a hierarchy of Region → Country, you'll see a subtotal column for each region. - Columns → Grand Totals — a single row at the bottom of the visual aggregating across all rows. - Columns → Totals — the same behaviour on the column hierarchy. Subtotals only appear when the relevant axis has two or more hierarchy levels — there is nothing to "sub-total" when there is only one level on an axis. ## How totals are calculated Totals and subtotals are recomputed from the underlying rows, not aggregated from the visible data in the cell. This distinction matters most for non-additive aggregations: - Averages show the true mean across all rows, not the mean of the displayed means. - Distinct counts show the distinct count over the broader rollup, not the sum of child distinct counts. - Sums, counts, mins, maxes, medians and percentiles behave the same way — each total is computed over the expanded row set. Because totals are computed from rows, they reflect the same calculation you defined for the leaf cells — including calculations you've authored yourself. Number formatting (currency, percentage, decimals) is inherited from each column. Filters on the visual still apply, so totals always agree with the rows shown. ## Supported visualisations Totals are available on visuals where summary rows and columns are meaningful: - Pivot tables - Heatmaps - All custom visuals Visuals without a row/column structure (e.g. scatter plots, single-value KPI cards) do not show the Totals control. ## Notes - Subtotals require ≥ 2 hierarchy levels on the axis they're displayed on. If you've only added one field to the row or column axis, only grand totals are available for that axis. - Totals follow the aggregation defined on the measure. To change how a total is computed, change the measure's aggregation — there is no separate "totals aggregation" setting. #### Logic options URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/logic-options Logic options When you add a column to a visual, you can configure it in two ways: Logic and Display. These options are available from the ellipses (...) menu next to the column name in the design bar. - Logic – Controls how the column is calculated or aggregated. - Display – Controls how the result is formatted and shown in the visual. ## Logic tab The Logic tab lets you choose how to calculate or transform the data in a column before it’s plotted. ## Text fields For categorical or free-text fields, you can only use functions that make sense for non-numeric data: - No function – Show raw text values. - Count – Count all rows. - Count distinct – Count unique text values. - Minimum / Maximum – Return the first or last value in sort order (e.g. alphabetically). - Edit expression… – Write a custom expression (see calculations in visuals). - Remove – Remove the column from the visual. ## Numeric fields For numeric values, you’ll see the full set of aggregations: - No function – Show raw values (only available in some visual types). - Total / Sum – Aggregate values by summing. - Average – Mean of the values. - Minimum / Maximum – Lowest or highest value. - Count – Count of rows. - Count distinct – Count of unique values. - Mode, Median – Most common or middle value. - Standard deviation (sample / population) – Spread of the values. - Variance (sample / population) – Variability of the values. - Bin – Bucket values into ranges. - Table calculation… – Apply a secondary calculation across the table (see Table calculations). - Edit expression… – Write a custom expression (see calculations in visuals). - Remove – Remove the column from the visual. ## Date fields For dates and times, you can aggregate by measure or transform into parts of a date: - No function – Show raw date values. - Minimum / Maximum – Earliest or latest date. - Count / Count distinct – Count rows or unique dates. - Truncate to date part – Year, Quarter, Month, Week, Day. - Extract repeating part – Month of year, Week of year, Day of year, Day of month, Day of week. - Table calculation… – Apply a secondary calculation across the table (see Table calculations). - Edit expression… – Write a custom expression (see calculations in visuals). - Remove – Remove the column from the visual. ##### Table Calculations URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/logic-options/table-calculations Table Calculations Table calculations are a special type of transformation available in the Logic tab. They calculate values relative to the table, pane, or cell after data has already been aggregated in your visual. ## Calculation types Currently, the following calculations are supported: 1. Percent of total – Express each value as a percentage of the total, based on the chosen context. 2. Percentile – Assigns each value its percentile rank within the chosen context. 3. Rank – Assigns each value its rank (1 = lowest/highest depending on sort direction) within the chosen context. ## Context options The Context setting defines the scope over which the calculation runs: 1. Table – Uses the entire table (all rows and columns together). 2. Table (down) – Runs down each column. Each column is calculated independently. 3. Table (across) – Runs across each row. Each row is calculated independently. 4. Pane – Uses only the current pane (for visualizations with facets, each pane is calculated independently). 5. Pane (down) – Like Table (down), but scoped only to the current pane. 6. Pane (across) – Like Table (across), but scoped only to the current pane. 7. Cell – Uses only the value of the individual cell (for Percent of total this is always 100%). ## Direction options For Percentile and Rank, you can also choose a Direction: • Ascending – Smallest value = lowest rank/percentile. • Descending – Largest value = lowest rank/percentile. ##### Binning URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/logic-options/binning Fast histograms! Binning groups numeric values into ranges (“bins”) instead of showing each unique value. This is commonly used for histograms, frequency distributions, or when you want to simplify data with lots of distinct values. You can enable Binning from the Logic tab options of a numeric field in a visual: - Bin (toggle) – Turns binning on for the field. - Width – Sets the size of each bin. For example, with a width of 30, values are grouped into ranges like 0–30, 30–60, 60–90, and so on. If you want more control over how values are grouped, you can create a custom expression instead of using the default binning. This lets you define your own logic (for example, with a CASE WHEN expression) to set custom ranges, categories, or thresholds. Learn more about custom expressions. #### Display options URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/display-options Customise how your visual is displayed. When you add a column to a visual, you can configure it in two ways: Logic and Display. These options are available from the ellipses (...) menu next to the column name in the design bar. - Logic – Controls how the column is calculated or aggregated. - Display – Controls how the result is formatted and shown in the visual. The options available in the Display tab depend on the type of data (Numeric, Date, or Text). ## Numeric fields When the field contains numeric values: - Title Add a custom axis or label title. - Type - Discrete – treat values as categories. - Continuous – treat values as a range. - Sort (Discrete only) - Natural – numerical order from smallest to largest. - Alphabetic – A → Z. - Column – sort by another column’s values. - Manual – drag and drop to reorder. - Scale (Continuous only) Choose how values are scaled: - Linear – evenly spaced values. - Logarithmic – compress large ranges using a logarithmic scale. - Base: set the log base (default 10). - Power – apply an exponential scale. - Exponent: set the exponent (default 1). - Symmetric log – logarithmic scaling that supports both positive and negative values. - Base: set the log base. - Additional options: - Domain (min / max) – set custom axis limits. - Reverse scale – flip axis direction. - Round limits – round axis limits to cleaner values. - Use secondary axis – add this field to a second axis. - Format - Apply to Axis, Labels, or All. - Options include number type (Automatic, Number, Percentage, etc.), decimals, display units (e.g. Thousands, Millions), negative value style, prefix/suffix, and thousands separator. - Axis and Tooltip Toggle whether they are displayed. ## Date fields When the field contains dates: - Title Add a custom axis or label title. - Type - Discrete – show dates as categories. - Continuous – show dates along a timeline. - Sort (Discrete only) - Natural – chronological order of the values in the column (for example, days of the week run Monday, Tuesday, Wednesday etc. starting from your defined first day of the week). - Alphabetic – A → Z. - Column – sort by another column’s values. - Manual – drag and drop to reorder. - Scale / Domain (Continuous only) - Domain (min / max) – set start and end dates for the axis. - Reverse scale – flip axis direction. - Round limits – snap axis ends to cleaner dates. - Use secondary axis – place dates on a second axis. - Format - Apply to Axis, Labels, or All. - Options include date style (short, medium, long), custom formats, etc. - Axis and Tooltip Toggle whether they are displayed. ## Text fields When the field contains text/categorical values: - Title Add a custom axis or label title. - Sort - Natural – for strings natural order means alphabetical order of the values in the column. - Alphabetic – A → Z. - Column – sort by another column’s values. - Manual – drag and drop to reorder. - Axis and Tooltip Toggle whether they are displayed. #### Color, size, opacity & dash URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/color-size-and-opacity Differentiate data in visualizations using color, sizing, opacity and stroke dashes. You can set colors in two ways: - Assign a single color – Use the color picker, enter a HEX code, use the dropper to match a color from the canvas, or select from the Shared styles tab. - Map a column to color – Drag a continuous or discrete column into the Color field. ## Assign a single color You can do this in a few ways by: - Selecting a color from the palette - Entering in the Hex code of a color - Using the dropper to match another color from the canvas - Select a shared color by clicking on the Shared tab. Learn more about Shared styles. It is also possible to adjust the Opacity of the selected color, either using the slider or by entering an Opacity percentage. ## Discrete color mapping You can map a discrete column on the Color field by dragging it to the Color channel. To customize this mapping further: - Click on the ellipses (...) beside the column name and choose from logic and display tab options. - To change the colors being mapped to discrete columns, in the Display tab either: - Select a palette – Choose a default palette from the dropdown, or create your own custom palette. - Reorder colors – Drag the color icons to change their order. Colors are applied left to right based on category order. - Edit overrides – Click Edit overrides to manually assign colors to specific categories. ## Continuous color mapping Mapping a continuous color can be done in the same way, though the Display options to format this are different: - Choose a Scale: Options include Linear, Logarithmic, Power, or Symmetric log. Each has additional configuration fields. - Customize a palette: Pick a predefined palette from the dropdown, or choose Custom to create your own. When customizing: - Click a square above the gradient to change its color, or press Delete to remove it. - Drag the squares along the gradient to adjust their position. - Click anywhere on the gradient to add a new square. - Click Save palette to save it as a shared style in your canvas. - Set the number of steps: Adjust the number of color steps available in the gradient. ## Size - Assign a fixed size – Click on the icon beside the Size field to apply the same size to all data points. - Map a column to size: - Drag a column into the Size field to size marks dynamically based on data values. - Click on the ellipses (...) menu for logic and display tab options. - Select to Display tab to customize the formatting. In this example, I have changed the 'Range' values to adjust the mimum and maximum sizes of the circle marks in this visualization. ## Opacity - Set a fixed opacity – Select the icon beside the Opacity field and use the slider or enter a percentage. Map a column to opacity: - Drag a column into the Opacity field to vary transparency based on data values. - Click on the ellipses (...) menu for logic and display tab options. ## Stroke dashes Line marks can also be assigned stroke dashes: - Fixed stroke dash - click the line icon next to the Stroke dash field to choose one of several dash options. Alternatively, select Custom to enter your own dash specification (see below). - Map a column to stroke dash - drag a column onto the Stroke dash field to vary the dash style based on the column values. This works best with low-cardinality columns. Custom dash styles Custom dash styles are defined by entering a dash string: The format of the custom style string is , , , ... Typically you'd enter 2 numbers, but it's possible to add as many as you like. ## Troubleshoot How do I maintain consistent color mapping when a value is missing? ## Color mapping with missing values The guide explains how to maintain consistent colour mapping when a value is missing, ie to resolve issues like this: ### Why using a discrete color palette causes issues Discrete color palettes assign colors according to the sorting and number of values in a field - if the number of values changes, then the assigned colors will change. Why is this important? If you want your values/variables to have the same color, even if the scale/range in your data changes, you can make some edits to the color palette feature to keep the colors fixed to the variable. When using a discrete color palette, colors aren't assigned to specific values. ### The Solution: assign colors to categorical variables via a complementary continuous field If your dataset doesn't already have a numerical key assigned to your categorical variable, then you can create one. In the example dataset, each status value has a corresponding status_id. 1. We will pull status_id into Color on the visual design tab, and pull status into Label. 2. Define the Domain (min) and (max), and Number of steps according to the data range of the numerical key column. Now the colors should stay consistent, even if the distinct number of categorial variables in the field changes. #### Column summaries URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/column-summaries How to get a column's distribution, top values, or range in one click. ## Create a column summary chart Drag any column from a cell, table, or CSV cell from the data side bar into the canvas to generate an automatic visual summary of that column. ## Summary types Depending on the data type of your column, different column summaries are created: - Numerical columns - binned histograms - Datetime columns - time series - All other column types - horizontal bar charts #### Tables URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/tables How to create a table. Tables excel at presenting precise data with clear row/column comparisons that anyone can interpret instantly. They're versatile enough to show everything from detailed breakdowns to high-level summaries, making complex information accessible. ## Adding in a table There are two ways to add in a table: - Toolbar -> Low-code -> select Table - Select an existing cell and press '+' (add a cell) -> select Table ## Formatting your table - Customize easily by adding titles, drag columns into place, apply filters, and style to match your needs. - Tables display up to 10,000 rows by default, but you can set custom limits or choose unlimited rows. - Export as SQL, PNG, PDF, or CSV to distribute your data in any format and share seamlessly. ### Table versus pivot table Table Cell: • Great for quickly visualising your data • Easy sorting and filtering • Can work with aggregated data from the SQL cell • Good for exporting the CSV in the same format Pivot Table: • Great for summarising data • Easy grouping across rows/columns • Less flexible around sorting/filtering • Cannot export pivots in their pivot format ## Troubleshoot How do I add conditional formatting to tables? ## Adding conditional formatting Count offers two ways to highlight table data: 1. Text-level highlighting – This will change the color of the text 2. Full cell background highlighting – This changes the background color of the entire cell You can use SQL’s CASE statement to apply conditional logic and return values that can be highlighted in tables visualisations. ### How to color individual values in a table With the custom table visualisation, you can easily change the color of your text mark by adjusting settings in the right-hand panel. First, set up your thresholds using a CASE statement (you can do this in a SQL cell or a calculated field!) to create a new column, then use this column to automatically change the color of your table's text mark based on the values. ### How to color individual rows in a table Similar to the text coloring, we can make use of marks in the custom table visualisation to easily change the background colors of rows by adjusting settings in the right-hand panel. Set up your thresholds using a CASE statement to create a new column, then use this column to automatically change the color of your cell background. How do I create tables with coloured flags? ## Creating tables with coloured flags Coloured flags in tables helps analysts and key stakeholders quickly identify trends and anomalies. Here, we will identify how to: - Add numbers with a colour scale - Add performance flags ### Numbers with a colour scale The fields 'WoW %' and 'YoY %' are common performance metrics that are often coupled with a colour scale indicating whether an outcome is positive or negative. To add a colour scale such as red and green: 1. Pull the chosen field into Colour under the Custom tab. 2. Select the colour range and specify the Number of steps - here we've chosen 2. 3. If you're working with % values, define the domain min and max as -1 and 1 respectively. Otherwise, define according to your data range. ### Performance flag You can enable even quicker identification of summarised performance at a glance. In the source data, we've created a summary field with assigned colours. We assign these based on metric performance across fields: 'green' for all positive values, 'red' for all negative, and 'orange' for mixed results (you could do this via a case statement). Once the summary column is ready, you can pull the summary performance field under a Circle or SquareMark. Then, pull the field into Colour and match the colour to the summary value. #### Maps URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/maps Visualize data on maps with point or geoshape templates. Customize with longitude, latitude, size, color, and detail for dynamic geographic insights. Maps plot data as points, regions, or text on a geographic base map. Count uses OpenStreetMap for the base layer. [Video: Introducing Maps in Count] There are two ways to map data: - Points — when each row has its own latitude and longitude. - Regions — when each row corresponds to an area (a country, a US state, a UK local authority, a custom polygon, …). You can see sample data and Map visuals in this canvas. ## Creating a map To add a map to the canvas, either: - In the control bar at the bottom of the canvas, open the Visual group, choose Map, then click on the canvas to place it. - Press G, then click anywhere on the canvas to place it. ## Point template When each row of your data has a coordinate, use the Point template. ## Region template When each row of your data corresponds to an area, use the Region template. Region marks have a Source setting that controls where the shape comes from: - Official boundaries — Count looks up the shape for you from a built-in dataset (e.g. UK Local Authorities, US Counties). You only need to provide the boundary's name or code. - Custom geometry — you provide the shape yourself as a GeoJSON or WKT string in your data. ## Official boundaries Official boundaries let you draw regions on the map without having to ship geometry in your data. Count keeps an up-to-date library of administrative boundaries published by official sources — Natural Earth, the US Census Bureau, Eurostat GISCO, the UK ONS, and more — and resolves them at render time from a name or code in your column. This is usually what you want when your data already has a familiar identifier like a country name, a US state code, a ZIP code, or a UK local authority code. ### Getting started - Add a Geo mark to your map layer. - In the right-hand panel, set Source to Official boundaries. - Pick a Dataset (e.g. Countries, US Counties, UK Local Authorities). - Drag the column that identifies each region onto the Region field. That's it — Count fetches the matching shapes and draws them. Rows whose value doesn't match any boundary in the dataset are skipped silently, so you can keep working without cleaning the data first. ### Matching rules Count tries to be forgiving about how your identifiers are spelled. Each dataset uses one of two matching modes: - Aliases — matches against the boundary's canonical code as well as a curated list of common names and aliases, and is tolerant of differences in case, punctuation, and accents. So Côte d'Ivoire, Cote d'Ivoire, and the ISO code CIV all resolve to the same country. - Canonical only — matches against the boundary's official code only. Used for datasets where there is no meaningful "common name" (e.g. census tracts, output areas). The mode is fixed per dataset — see the table below. ### Examples ### Available datasets Global United States All US datasets use the US Census Bureau's TIGER/Line files and key off the GEOID. Europe Sourced from Eurostat GISCO. United Kingdom UK datasets are sourced from the Office for National Statistics Open Geography, Scottish Government Open Data, and NISRA Open Data. ## Custom geometry If your data already contains polygon definitions — or if you need a boundary that isn't covered by the official datasets — set Source to Custom geometry and drop a column of GeoJSON or WKT onto Region. #### Dynamic text URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/dynamic-text Merge data + text Dynamic text lets you embed live data directly into your text. It behaves like normal text - you can format it, resize it, and place it in headers, lists, sticky notes, or shapes - but the content is linked to a cell. If the source cell updates, the dynamic text updates automatically. ## Insert dynamic text - Click into a text area where you would like to insert dynamic text (e.g., a text box, sticky note, or shape). - Click the gauge icon to insert dynamic text. - Choose the source, cell, column, and row you’d like to pull data from. Once inserted, the text will update whenever the source cell changes. This means if the canvas is connected to a control cell, any updates made by a user will flow through to connected cells and dynamic text automatically. ## Edit or remove dynamic text - Hover over existing dynamic text to reveal options to edit or remove the link. Make sure the referenced cell is ordered using an ORDER clause to ensure the correct row order. - Explore how to add dynamic comments into charts in our visualization guide. #### Visualization tips URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/visualization-guide Some tips and tricks to excel your visualizations. This guide combine best practices with solutions to common challenges, enabling you to develop more effective and compelling visualizations. ## Structural design Learn layout techniques to organize your data. Using facets versus subplots Both facets and subplots can be used to help structure visuals. Facets - partition data into distinct groups and repeat the subplot(s) for each group, allowing hierarchies with up to 8 levels. - In the visualization Design panel, add the field you'd like to partition by to Facet, using the option of row and/or column. Subplots - enable multiple marks along a shared axis with separate scales on the other, supporting up to 64 subplots in an 8x8 grid. - Add each new plot as a new Mark, increasing the Subplot y-axis by 1 each time to position each new visualization under the previous. ## Styling & annotations Enhance charts with visual elements, comments, and professional formatting Add 'dots' to a linechart Adding dots to a linechart can be a simple way to clearly identify the key data points along the trend line. - With your visual in Custom view, duplicate the Line Mark you'd like to add dots too. - Change the Mark type to Circle. Add dynamic comments to a chart Using dynamic comments on a chart means they will be self-service, updating alongside your data. - Create a SQL cell and manually define the comment to add in (e.g one column is a date, another is the event). - Join this table to your dataset, so each column has the corresponding event against it. - Plot your data, then add a new Text Mark which will be the event field now joined onto your dataset. - Navigate to '...' to modify the position of your dynamic comment in relation to the rest of the visual. ## Advanced analytics Explore methods for more advanced and statistical chart outputs. Visualize a moving average - Create an initial Mark (e.g. daily conversion rate) using a calculated field - Add a second Mark with the same x-value, and use the custom field below to add a 30 day window as the second calculated field. - Navigate to ...(More) -> Show marks legend to add a legend for both marks in. Create an A/B scatterplot Count streamlines A/B testing with collaborative scatter plots that let you query, analyze, and visualize test data in one workspace. Easily spot group differences, refine analysis, and share insights across departments without switching tools. - Click '+' from a SQL cell to create a visual - Choose one of the Scatter visual options - Set up the scatter plot, selecting the x and y values, adding the A/B test split into Color to differentiate between your groups. Add an average line to a chart - Select your visual and add a new Mark type (Line) - Drag the relevant field into the x-axis column (e.g., Date) - In the y-axis column, format the calculation to add AVG(Value) OVER (), replacing Value with the field to find the average of #### Calculations In Visuals And Low Code Cells URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/calculations-in-visuals-and-low-code-cells Leverage the full power of SQL without the boilerplate Calculations allow you to perform more complex analyses than possible with the built-in functions available in the visual/low-code UI, without having to write a full SQL statement. Calculations in Count are SQL expressions, written in a syntax that is heavily influenced by DuckDB (itself similar to PostgreSQL). They can be used with all databases supported by Count and — depending on the database — are parsed and transliterated to the appropriate dialect as required. ## Getting started You can apply calculations to selects, filters and join constraints in visuals and low-code cells. In order to add or edit a calculation, either: • Double click on a drop target or select to get an inline-editor • Click on a select, filter or join constraint and select Edit calculation... to bring up the calculation modal Once you're happy with your calculation, submit it using Shift + Enter. Rename your column You can also rename the field for additional clarity or to clean up the text. Click 'Display' -> Alias -> Rename your column ## Expressions Calculations in Count support the following expression types: • Literal (0, 0.123, 'abc', NULL, TRUE, FALSE) • Identifier (Sales, Orders.Sales) • Function (sum(Sales)) • Between (Sales BETWEEN 10 and 20) • In (Region IN ('East', 'West')) • Case (CASE WHEN Region = 'East' THEN 0 ELSE 1 END) • Cast (CAST(Sales AS VARCHAR)) • Binary (2 + 2, A OR B) • Unary (-2, NOT TRUE) There's no explicit limit to the length of calculations. ## Operators The precedence of operators (the order in which expressions are evaluated) follows that of PostgreSQL. Parentheses can be used to override this. ## Types The following data types can be used in CAST expressions: • VARCHAR ('abc') • DOUBLE (1.23) • INTEGER (123) • DATE (DATE '2024-01-01') • TIMESTAMP (TIMESTAMP '2024-01-01T00:00:00') • TIMESTAMPTZ (TIMESTAMPTZ '2024-01-01T00:00:00Z') • BOOLEAN (TRUE) ## Functions Count supports the following functions (note that some functions may be unavailable on some databases): ### Text ### Numeric ### Date Intervals take the form of: • INTERVAL x • INTERVAL 'x y z ...' and the following are valid date parts: • YEAR, YR, Y, YEAR, YRS • QUARTER, QUARTERS • MONTH, MON, MONTHS, MONS • WEEK • DAY, DAYS, D • HOUR, HR, HOURS, HRS, H • MINUTES, MIN, MINUTES, MINS, M • SECOND, SEC, SECONDS, SECS, S • MILLISECONDS, MILLISECOND, MS, MSEC, MSECS, MSECOND, MSECONDS • MICROSECONDS, MICROSECONDS, US, USEC, USECOND, USECONDS[^1] ### Date part ### Aggregate ### Window ### Utility [^1]: #### Joins In Visuals And Low Code Cells URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/joins-in-visuals-and-low-code-cells >- You can join tables/cells together in visuals and low-code cells by clicking Add join... in the base table column selector. You can then choose the join type (inner, left, right, full) and the table or cell you want to join. Count will suggest join constraints based on: • Other low-code or visual cells in the canvas that join these two tables • Columns in the two tables To change these constraints, click on the drop-downs or select Edit calculation... from the ellipsis menu to apply an arbitrary calculation. #### Visual recipes for the agent URL: https://learn.count.co/analytics-engine/cells-overview/visual-and-low-code-cells/building-visuals-with-the-agent Build impactful charts faster with reusable agent prompts. Count has always had a powerful, flexible visualisation engine (see some examples in our Every Visual Under the Sun canvas). Now, working with the agent, you can build impactful visuals like these with very little manual effort: describe what you want instead of building it step by step. Below are a few examples, each with the finished visual and the prompt for you to reuse. How to use these: - Copy and paste the prompt into your canvas. - Edit the text to add information about the data you would like to use, and any other changes you would like. - Feel free to ask the agent to edit the prompt for you if you want to make substantial changes to the charts. - Either paste your finished prompt into the agent, or simply select the text box while you write a short prompt asking the agent to build the chart. ### Timeline with key events highlighted Prompt to build this chart: Combo chart with event callouts My data Use when the series is continuous and a smooth between-point path helps readability. Start with a canvas cell containing date and value; sort by date and retain every observed point. 1. Build the smoothed series Build a Python output called cubic_spline_series. Convert dates to elapsed days, solve a natural cubic spline (second derivatives = 0 at both endpoints), and evaluate eight evenly spaced positions within each original interval. Output date, smoothed_value, and original_value. Set original_value to NULL on interpolated rows, retaining it only at original observation dates. Sort by date. 2. Build the two-layer chart - Line: x = date; y = smoothed_value; fixed colour #ED1AE8; tooltip hidden. - Points: x = date; y = original_value; circle size 4; fixed colour #ED1AE8. This makes hover show observed values only. 3. Apply the finish - If using the cubic spline, title the chart [Metric name] (smoothed) in Roboto Mono. If switching to a raw line, title it [Metric name]. - Axis titles: bold Roboto Mono. - Gridlines: off (lines.grid: null). - Place the chart and caption inside one thin 1px #ED1AE8 frame. Remove any separate chart-only outline, and use a minimal gap (about 4px) between the chart and caption. - Date labels: day + short month. - Value labels/tooltips: number, 1 decimal, thousands separator. - Cubic-spline caption (only when smoothing is retained): Method note: Line is a cubic-spline smoothing of the weekly averages; dots are the actual figures. Replace ‘weekly’ with the relevant cadence. If switching to a raw line, adjust this method note accordingly. 4. Size the chart for the data Choose dimensions from the number and density of plotted dates, the cadence, and rendered label legibility. Keep the chart landscape; if labels or local movement crowd, widen it or use a business-meaningful coarser cadence—never squeeze or scroll the plot. Guardrail Natural cubic splines always pass through observed points, but can overshoot around sharp period-on-period swings. If that could materially change interpretation, use a shape-preserving smoother or a raw line instead. When using a raw line, remove all smoothing language and the overshoot caveat; the line and dots are then the exact observed values. ### SQL cells URL: https://learn.count.co/analytics-engine/cells-overview/sql-cells SQL cells are the analysis workhorse of Count ## Creating a SQL cell To create a SQL cell, click the cell button in the control bar, or hit the / key. You can drop your cell anywhere on the canvas and start writing SQL. Your query can use any of the tables, columns or cells you see in the data bar on the left hand side of the canvas. When you create a cell, it will reference the currently-selected data source in the sources pane of the data bar. ## Writing and formatting SQL Cells use the syntax for your database. For example, if you are querying Snowflake you should use Snowflake syntax and functions. If you switch to BigQuery, write in native BigQuery SQL. SQL cells have a few great features: - Contextual auto-complete - Count will suggest table names, column names and functions depending on the scope of the SQL you are writing. - SQL linting - Accessed via the design bar or right click menu, Count will automatically format your SQL to be easy to read. - Automatic DAG creation - Count will automatically connect any SQL cells that reference one another with an arrow. - Automatic cell layout - Available with the keyboard shortcut Cmd/Ctrl+Opt/Alt+L, Count will automatically selected cells in a logical manner. - Exploding cells - Turn any query involving CTEs into a DAG of connected cells. - Jinja templating - Use the jinja templating language to generate queries. ## Exporting SQL from Count Each cell, regardless of type, is a SQL statement under the hood. You can export that SQL via the right-click menu by choosing Copy compiled SQL. It's important to understand that any given cell contains the SQL for all cells upstream in the DAG. This means you can export SQL from the last cell in a complex chain of analysis and export it to any database or data tool. This is often used for materializing views in a database. Remember, each cell in Count is one or more compiled CTEs. Because we use the native SQL of your database, you can plug-and-play SQL from Count into your data source. ## SQL best practices Reduce data volume by only returning the data you need: - Avoid SELECT *, query only needed columns - Apply filters early in your query - Use INNER JOIN instead of LEFT JOIN + filtering - Add LIMIT when building up your analysis Improve SQL efficiency: - When dealing with arrays or JSON objects, filter before you explode the nested values into rows. - Avoid self-joins and consider using ARRAY instead. ### Control Cells URL: https://learn.count.co/analytics-engine/cells-overview/control-cells Designed to give more power to your audience [Video: Adding interactivity with Control Cells] [object Object],[object Object] Control cells make your reports interactive by allowing users to filter data directly on the Count canvas. They dynamically update downstream visualisations and tables. You can choose from the following types of interactive controls cells: - Number input - accepts number input. Can be used with condition options such as greater than, less than etc - Toggle input - an on/off field that accepts only boolean data - String input - a free-form text entry field - Single select - a drop-down to allow selection of a single element of a column (max 1,000 results) - Multiple select - a drop-down to allow selection of multiple elements from a column (max 1,000 results). - Slider input - a slider input to select a specific value. Can be used with condition options such as greater than, less than etc. Min and max values are configured in the design bar that appears on the right when the control cell is selected. - Date picker - a date selection cell to either an exact or relative time. - Table filter - a cell that directly presents all fields in a table (as selected in the right-hand design bar) with a built in mechanism for adding a filter. ## How to add a control cell to a canvas A control cell is added to your canvas by selecting it from the toolbar at the bottom of the screen ## How can I connect a control cell to a visualisation? We have 3 methods for setup, based on different use cases: - I would like ALL visualisations & tables downstream to be filtered - I would like to select SPECIFIC downstream visualisations & tables to be filtered - I would like to embed a filter in a sql query 1. Filter ALL downstream cells Example use case: in a traditional dashboard, we might want to filter all the visualisations that appear by a field called country_code. - We add a control cell to the canvas by selecting control cell from the bottom toolbar. - We select the type of control cell and where to put it on the canvas. When we click on the control cell, a side bar appears. We give it a meaningful name (see 1 in Control cell sidebar image below). - In the next section down in this sidebar, where it says Cell/table select the table or view containing the source data for the visualisations and just below, the name of the field you want to use as a filter (see 2 in Control cell sidebar image below). - In the sidebar, under Automatic references, we select all the source data tables that should be referred to by this filter, including the one we already added in the previous step. Additional source tables are included by using the + symbol. For each source table (automatic reference) added, ensure we select both the source table and the field (constraint), clicking the 3 dots next to it (3 in Control cell sidebar image below). We do not need to specify the target cells as all downstream cells from the source tables will be affected by this filter. If we want to limit this within the canvas, we can do so by grouping the visual cells that should have the filter applied into frames and selecting the toggle to scope to a specific frame, available in the menu related to each automatic reference (3 above). 2. Filter some, but not all downstream cells Example use case: when you want to filter specific visualisations (e.g. regional sales charts) while keeping others, like national KPIs, unchanged. - We add a control cell to the canvas by selecting control cell from the bottom toolbar. When we select the control cell on the canvas, the side bar appears on the right. We give the control cell a meaningful name (1 in control cell sidebar image below). - In the next section down in this sidebar, select the name and field from the table or view that contains the source data (2 in control cell sidebar) of our visualisation. - We click back onto the visualisation we want to filter. In the design sidebar, we drag the field that we would like to filter the visualisation on onto the filters section (see 1 below). - Click the 3 dots next to the field name on filters (see 2 in design sidebar image above) and a menu pops up. Towards the bottom, we click on “Connect to control” (see 3 in image above) and select the letter name of the control. We have now connected this control cell to this visualisation. Other visualisation cells can be connected to that control cell in the same way, by adding the field to the filters section in the visualisation's design sidebar and following the steps to connect to a specific control. 3. Embed a filter in a sql cell We add a control cell to the canvas from the bottom toolbar as we have done before. We connect it to a sql cell by writing a query that references the control cell. To help you write your query, click on the control cell to see the manual references that are automatically generated in the sidebar. In the example below, the control cell is called Artist_Name and is referenced in the where clause in the query. The syntax may vary depending on the database you are querying. In the example below, the query has been written for BigQuery. You can either refer to control cells using pure SQL, or using Jinja templates. Below, a cell called genre control is referenced with a Jinja template. Users of Redshift may encounter errors when referencing control cells using SQL. ## Access control cells quickly You might have added multiple control cells across your canvas, making it difficult to pinpoint where they are in order to filter your data. In the Overview pane in your canvas, you can add your controls here to make them accessible wherever you or others are in the canvas - even in Report view. Overview pane -> Type '/' -> Select the control you want to add You could also add plain text into the Overview for additional context for the control cells. ## Allow users to interact with control cells Control cells will behave differently depending on whether a user has edit or view access to a canvas, and whether the canvas is locked or unlocked. The table below summarizes how these two states interact: In summary, if you want a canvas to act like a typical dashboard or notebook where many users are using filters independently then make sure you lock the canvas, but if you intend to use the canvas as a collaborative space, then keep the canvas unlocked and invite contributors to be editors. Tips 1. Make use of DuckDB Your Count canvas can query data from different sources: - A data warehouse, such as BigQuery, that allows cells to query tables within that database and other cells connected to it. - Local DuckDB, which allows cells to query the results of any other cell on the canvas, as well as uploaded CSV files. Control cells can only be attached to sources of the same type (e.g., you can connect a control cell to two DuckDB sources, but not to a DuckDB source and a BigQuery source). It’s best practice to first transfer data from your data warehouse queries into local DuckDB cells to ensure you can always connect a single control cell to all data on the canvas, regardless of the source. 2. Check for compatibility Control cells only function when attached to columns with compatible data types. For example: - A number input control cell should only be attached to a numeric column. - A toggle control cell should only be attached to a boolean-type column. #### Table filter URL: https://learn.count.co/analytics-engine/cells-overview/control-cells/table-filter A control cell that lets you filter a whole table, fast A type of control cell that directly presents all fields in a table with a built in mechanism for adding a filter. To use a Table Filter: - Select the Table Filter icon from the Control Cell options in the toolbar at the bottom of the screen, then click to add it to the canvas. - With the cell selected, choose the Source and the Cell/Table you want it to display. - At the top of the Table Filter, click Add Filter. Choose the field you want to filter on, select the logic, and define the value(s). - Repeat to add multiple filters if needed. #### Slider control cell URL: https://learn.count.co/analytics-engine/cells-overview/control-cells/slider-control-cell Alway variable inputs A Slider input allows users to select a specific value that you've set. They can be used with conditional options such as greater than, less than etc. Min and max values are configured in the design bar that appears on the right when the control cell is selected. #### Single And Multiple Selects URL: https://learn.count.co/analytics-engine/cells-overview/control-cells/single-and-multiple-selects How to use single and multi-select control cells. Single and multiple select control cells make your reports interactive by allowing users to filter data directly on the Count canvas. They dynamically update downstream visualisations and tables. ## Insert the control cell Use the canvas toolbar to insert a single or multiple select control cell: ## Configure the control cell For single and multiple-selects, there are several options for configuring the control cell: ## Dynamic This is the default option for these control cells - the values in the dropdown will be populated from the table or cell that you choose. The top 1000 entries will be shown, ordered by frequency. If another value is required that doesn't occur in the list, it can be entered manually. ## Static If the values of this control cell do not need to change, it can be made static. Options can be entered manually and ordered arbitrarily. If the selected values should be interpreted as a number, select that option from the Format list. In this case, any non-numbers will not be selectable. #### Date Controls URL: https://learn.count.co/analytics-engine/cells-overview/control-cells/date-controls How to filter for dates and date ranges. Date control cells can be configured by clicking on it and selecting either an exact or relative time. Hour-level granularity can be toggled on in the design bar on the right-hand side. ## Insert the control cell Use the canvas toolbar to insert a date control cell: ## Configure date controls Date control cells can return dates or timestamps - choose whether time information is returned using the Include time option: ## Select a date or timestamp Once the date control cell has been inserted, its value can be selected from the drop-down menu. Date values can be absolute or relative. #### Text, Number, and Boolean Controls URL: https://learn.count.co/analytics-engine/cells-overview/control-cells/text-number-and-boolean-controls How to use text, number, and boolean controls. ## Insert the control cell Use the canvas toolbar to insert the control cell you want to use. These simple controls include: • Number controls - type an arbitrary number • Slider controls - pick a number within a range by dragging a slider • Toggle controls - pick a boolean value by clicking a toggle switch • String controls - enter arbitrary text ## Configure slider controls Additional configuration options are available for slider controls - see the right sidebar while a slider control is selected: #### Combine control Cells with SQL URL: https://learn.count.co/analytics-engine/cells-overview/control-cells/control-cells-with-sql Use control cells to create interactive filters. Combining control cells with SQL allows you to create many bespoke, and powerful interactive elements. Explore examples of how you can customize control cells below: Interactive date filters Reference control cells in your query to link the results and all downstream cells to the control cell. 1. Add in one/multiple Date picker control cell/s 2. Reference your control cell in your SQL query select * from table where date_field between (select value from start_date_control_cell) and (select value from end_date_control_cell) 3. Now any changes to the control cell will update your query and all downstream elements including visuals, cells and tables. Custom date aggregations Create custom date aggregations to use as filters. 1. Add a Multiple select control cell 2. Click on the cell then navigate to Design panel -> Multiple select -> Static 3. Define the input Type (string for custom dates) -> Add in your filter Options one-by-one Below we have added in options for Daily, Weekly, Monthly and Yearly. Once added, these will then appear as options in your control cell. 4. Use a case when to add the control cell options into your query, the below code below can provide an outline for your code. select case when value = 'Daily' then day when value = 'Weekly' then date_trunc(day, week) when value = 'Monthly' then date_trunc(day,month) else date_trunc(day, year) end as date, artist, sum(streams) from `count-data`.spotify.spotify_daily_tracks, custom_date_select group by 1,2 Tip: Ensure an option has been selected in the multiple select, or the query has no reference point. Combining multiple control cells You can combine multiple control cells and reference all of these conditions in your query which will then impact all elements downstream. Let's expand on our previous example. Now we want to be able to adjust the start and end date of our dataset, and also select one or more artists. - Add in a Start Date and End Date date picker control cell - Add in a multiple select control cell, setting the cell/table datasource and column as the current datasource and required filter. - Use a where statement in the query combined with select value from control_cell to reference your new control cells. Custom search app Control cells can be used in a workflow to create a key-word based search app. Step 1: Create search input - Add a String input control cell, this will be your search bar. - Reference the control cell in your query, using regexp_contains() to add in advanced search conditions (e.g. lower/upper case). Step 2: Use control cells to reference the results - Use the results of step 1 by adding in another control cell e.g. a Single select, and reference the 'results' query as the cell/table and column for your control cell. - We can keep adding in control cells, for example below, we have added in a Number input control cell to apply an interactive 'rank' filter to our dataset. The result is a query which has taken a manual search term and output a filtered result using interactive controls. ### Python cells URL: https://learn.count.co/analytics-engine/cells-overview/python-cells How Python cells work in Count. Create a Python cell by either: - Using the Y keyboard shortcut to place a new cell - Selecting the Python cell option from the control bar - Selecting the Add Python cell option when referencing a cell from the + icon that appears when the cell is selected. ## How Python cells work Python cells work very similarly to SQL cells, consisting of a text input area and an output area. Python cells are reactive just like all other cells, and their relationships are indicated by the same connector lines. Python cells are executed on Count's servers in an isolated, sandboxed environment where network access can be controlled. Note: Legacy Python cells Older workspaces may still have canvases using our legacy, browser-based Python runtime. See here for information about this and about how to migrate to the new server-based Python runtime. ## Referencing other cells using the cells variable In Python cells, there is a special global cells variable that contains the results of other cells formatted as pandas DataFrames. Access cell results using keys or attributes on this object: Most operations work the same way on categorical vs non-categorical columns, but if a non-categorical form is required, then use the astype method: ## Referencing Python variables Each Python cell is run independently of any others. For this reason, variables defined at the root scope of one Python cell are not available in any other Python cell (they do not shared any scope). ## Referencing Python cells from DuckDB The last expression in a Python cell is special, and becomes the single output of that cell. If this output can be represented as a table, it can be queried by local DuckDB cells too: ## Python cell outputs As Python is a more expressive language than SQL, it is able to output more data types: - Table output - if the final expression of the cell is representable as a table - Image output - if the final expression of the cell is a PNG-formatted image bytes object - Logs output - if the cell has printed anything during its execution The output type defaults to Automatic, which can be overridden from the Output type button above the cell. ## Interactivity Because Python cells work just like any other cell, you can use control cells to add interactivity to any Python cell. In the example below, the parameters of a plot are adjustable using control cells: ## HTML outputs If a Python cell returns an object with an HTML representation, a View output button will appear. Clicking this button will cause the output to be displayed in the output section of the cell. To close a HTML output, click the Close rich output button from the floating cell controls: ### Technical details An object is considered to have HTML output if: - It has a method called _ipython_display_ which returns a string - It has a method called _repr_html_ which returns a string - It has a method called _repr_mimebundle_ which returns a dict with a key text/html Any HTML output is contained within a sandboxed iframe, so some functionality may be restricted. Most existing packages which conform to the IPython standard methods described above should work with Count. If you encounter a package which does not work as expected, please contact Count support. ## Python packages Any public package on pypi.org should be available to use. To load a package, just import it as usual and Count will attempt to automatically download it and make it available. To use a specific version of a package you can either: Use "Inline script metadata" (see here) to define dependency at the top of your cell like this: Or use Jupyter notebook style magic pip commands like this: Private Python packages are not currently supported. ## Performing network requests Network requests can be made by Python cells (e.g. using packages like requests and urllib3) provided it is allowed by your workspace. Specifically workspaces can be configured to: - allow all network requests; or - allow only network requests to specific domains (if no domains are specified then network requests are blocked completely) Maximum request payload limits apply, so network requests will fail if they attempt to send too much data. ## Using secrets Network requests made by Python cells can also reference secrets (e.g. API tokens) as below: The Python code itself won't be able to access this secret. Instead get_secret("my_secret") returns a random token which will be substituted for the real secret as part of proxying the network request. This keeps your secret safe from being accidentally leaked. Secrets can be configured at both the workspace and project levels (project secrets will take precedence if secrets share the same name). Secrets must be scoped to specific domains (even if network access is otherwise unrestricted). There are some security considerations to note when using secrets in Python cells: - Secrets can only be used in network requests. - Secret values are inserted into the network requests and then sent to the URL specified in the request. - Secret values are not accessible from the Count app regardless of your permission level. - If you grant analyst access to a canvas, you should assume that the editor will be able to access any secret you have defined by, for example, sending it to a URL that they control. - You should never directly enter a secret value into the text of a Python cell, as it will be visible to all viewers of that canvas, even if the cell input is hidden. Be careful when using libraries which transform secrets. For example, instead of using the auth parameter in requests (which automatically base64-encodes its arguments), construct the Authorization header manually. ### Legacy Python cells URL: https://learn.count.co/analytics-engine/cells-overview/legacy-python-cells How legacy Python cells work in Count. Most workspaces will no longer be able to use our legacy browser-based Python cells. If your workspace is able to use them, you'll see this option within each canvas, that allows you to switch between the standard, server-based Python runtime and the legacy, browser-based Python runtime. In order to migrate existing legacy Python cells to the standard, server-based ones, just update the above toggle for the canvas. One important difference between the runtimes is that legacy, browser-based Python cells shared the same global scope within a canvas but the server-based Python cells do not (they can only reference the output of other cells). This may mean you need to make some changes to the code in your Python cells in order to switch from the legacy runtime to the standard runtime. If your workspace isn't able to use legacy Python cells but for some reason you want to, please contact the Count team. Note: Legacy feature The following applies to the legacy, browser-based Python runtime. See here for the standard Python runtime in Count. ## Creating Python cells Create a Python cell by either: - Using the Y keyboard shortcut to place a new cell - Selecting the Python cell option from the control bar - Selecting the Add Python cell option when referencing a cell from the + icon that appears when the cell is selected. ## How Python cells work Python cells work very similarly to SQL cells, consisting of a text input area and an output area. Python cells are reactive just like all other cells, and their relationships are indicated by the same connector lines. In Count, Python cells are executed locally in your browser using a version of Python that has been developed to work on the web. When you first execute a Python cell, the Python environment is downloaded and started, which may take a few seconds the first time. ## Referencing other cells using the cells variable In Python cells, there is a special global cells variable that contains the results of other cells formatted as pandas DataFrames. Access cell results using keys or attributes on this object: When importing non-Python cells as DataFrames, text columns may be imported as a categorical series if the cardinality of the column is low. This lowers the memory usage of the column, which is helpful when importing large result sets. Most operations work the same way on categorical vs non-categorical columns, but if a non-categorical form is required, then use the astype method: ## Referencing Python variables All variables defined at the root scope of a Python cell are global, and can be accessed in any other Python cell. Count will detect relationships between Python cells based on the variables they reference, and add connector lines automatically. Because Count executes cells reactively, it's possible to accidentally create circular dependencies. In this case, like other cells, Python cells will display an error and refuse to execute: ## Referencing Python cells from DuckDB The last expression in a Python cell is special, and becomes the single output of that cell. If this output can be represented as a table, it can be queried by local DuckDB cells too: ## Python cell outputs As Python is a more expressive language than SQL, it is able to output more data types: - Table output - if the final expression of the cell is representable as a table - Image output - if the final expression of the cell is a PNG-formatted image bytes object - Logs output - if the cell has printed anything during its execution The output type defaults to Automatic, which can be overridden from the Output type button above the cell. ## Interactivity Because Python cells work just like any other cell, you can use control cells to add interactivity to any Python cell. In the example below, the parameters of a plot are adjustable using control cells: ## HTML outputs If a Python cell returns an object with an HTML representation, a View output button will appear. Clicking this button will cause the output to be displayed in the output section of the cell. Only one HTML output can be displayed at once - if another output is shown, the previous output will be hidden. To close an output, click the Close rich output button from the floating cell controls: ### Technical details An object is considered to have HTML output if: - It has a method called _ipython_display_ which returns a string - It has a method called _repr_html_ which returns a string - It has a method called _repr_mimebundle_ which returns a dict with a key text/html Any HTML output is contained within a sandboxed iframe, so some functionality may be restricted. Most existing packages which conform to the IPython standard methods described above should work with Count. If you encounter a package which does not work as expected, please contact Count support. ## Python modules To load a module, just import it as usual and Count will attempt to automatically download it and make it available. The first import of a new package may take a few seconds for this reason. As your Python code is running in your browser, there are some restrictions on the modules that you can load. Available packages include: - pandas - numpy - matplotlib - scipy - scikit-learn - Any module hosted on PyPi that is written in pure Python - Any module specifically built for running in the browser. Many popular data-focussed modules are already supported, with more on the way. See the full list here. ## Performing network requests The popular requests and urllib3 modules are supported in Count, with the exception of streaming responses - responses are always loaded fully into memory. When making a network request from Python, a description of the request is sent to a Count server, and the actual request is performed by an ephemeral virtual machine. The response is then proxied back through a Count server, and returned to your browser. Count does not read the response, though it may read the request to inject secrets (see below). Maximum request payload limits apply, so network requests will fail if they attempt to send too much data. ### Running network requests in parallel Most Python modules expect network requests to be executed serially. If network requests are slow, this restriction can cause cells to execute slowly. It is possible to use the async features of the count_requests module to execute requests in parallel: We normally recommend using standard Python modules rather than any modules specific to Count - this case is a rare exception. ## Using secrets If your project has any secrets configured, it is possible to use these secrets in network requests. Just format the secret name (not value!) using the secret method exposed by the count_requests module. The result of this method is just another string which looks like $$abc123$$, so it can be used in other places a string is expected. For example: There are some security considerations to note when using secrets in Python cells: - Secrets can only be used in network requests. - Secret values are inserted into the network request once it arrives at a Count server, and then sent to the URL specified in the request. - Secret values are not accessible from the Count app regardless of your permission level. - If you grant edit access to a canvas, you should assume that the editor will be able to access any secret you have defined by, for example, sending it to a URL that they control. - You should never directly enter a secret value into the text of a Python cell, as it will be visible to all viewers of that canvas, even if the cell input is hidden. Be careful when using libraries which transform secrets. For example, instead of using the auth parameter in requests (which automatically base64-encodes its arguments), construct the Authorization header manually. ## Troubleshooting What order do my Python cells run in? Unlike in a Jupyter notebook where cells execute top-to-bottom, in Count your Python cells execute in DAG order, just like SQL cells. When opening a canvas containing Python cells, Count will: • Analyse all of the Python code and look for variable definitions and references. • Draw arrows between cells if we’ve detected that variables defined in one cell are referenced in another. • Download all of the imported modules and perform all of the imports. • Perhaps wait for any SQL cells to finish executing if any Python cells depend on them. • Execute the Python cells in order based on which variables they define. How do I stop Python cells executing? Currently it is not possible to stop the execution of a single Python cell. Instead, you can choose to restart the Python kernel - this will clear all variables from memory and re-initialise the Python session, and all of your Python cells will be re-executed in DAG order. Why does my imported Jupyter notebook not execute as I expect? When importing a Jupyter notebook, a common pitfall is to have variables defined multiple times in different cells. If this happens, the cells in Count may not execute in the order you expect (though it will be the same order every time the canvas is opened). You can always check where Count thinks your variables have been defined by following the cell connector lines to their source: I can't install a Python package! ​​​Not all packages are supported in Python cells, but many are. You can import a package in a Python cell by importing it as usual. If that doesn't work, then there are some other options you can try. ### Step 1: Use micropip Micropip is a library for installing Python packages, and is used like: import micropipawait micropip.install('my_package_name') If this step doesn't succeed, the cause might be: • The package contains non-Python native extensions, which need to be handled specially. Many popular packages have already been compiled to work in a web browser, but if not the process is quite tricky even for Python experts - see the instructions here. In many cases, it will not be possible to support this package. To check whether or not a given package uses native extensions, follow the steps below. • The package depends on other packages with incompatible versions. In this case it is often possible to install the package by using an older version. Follow the steps below To determine if your package is supported, you can try following these steps: ### Step 2: Find the package on PyPI. You can use the built-in search function, or try a search engine query for " PyPi". An example page for a package looks like this: ### Step 3: Find the.whl file for the package Click the Download files link, and look under the Build Distribution list for a file name that contains none-any: If the filename ends with this, it means that the package is pure Python, and it should be possible to load it in Count. If you can't find a .whl file that ends with none-any, then it is likely that the package contains non-Python extensions, and will need to be compiled to work in the browser. ### Step 4: Load the .whl file in Count Copy the link to the .whl file (right-click > Copy link address), and import it in Count using micropip: # This function avoids using an import statement to import the package, which is useful# if you want to make sure that Count doesn't try to automatically import the latest# version of the package.async def import_package(url: str, name: str):import micropipawait micropip.install('setuptools')from importlib import import_moduleawait micropip.install(url)return import_module(name)airtable = await import_package('https://files.pythonhosted.org/packages/ec/2b/e5885493796ae222eac6d15ffab093cce8fe63bf10ee920ac205fa65e279/airtable-0.4.8-py2.py3-none-any.whl','airtable') ### Step 5 (optional): Install an older package version If the latest version of a package can't be installed, sometimes an earlier version can be. To find older package versions, click the Release history link and choose an older version. Then, follow steps 3 and 4 to try an older .whl file. My Python cells seem slow When executing a Python cell, the following steps are performed: • Imported packages are downloaded and installed (if needed) • Upstream cells are loaded into Pandas DataFrames • Your Python code is executed • The result of your Python code is converted into a table to be displayed Most of these steps should be quite quick. If a cell is slow, first try profiling your code to see if there are any particularly slow parts. For example, you could use the cProfile package to define a profile function: import cProfile, pstats, iofrom pstats import SortKeydef profile(func): pr = cProfile.Profile() pr.enable() func() pr.disable() s = io.StringIO() ps = pstats.Stats(pr, stream=s).sort_stats(SortKey.CUMULATIVE) ps.print_stats()return s.getvalue() which you would then use as follows: In this (trivial) example, it is clear that all of the time is spent in the regular expression constructor method __init__. If you do not identify any long-running parts of your code, and are concerned that your Python cells are slow for other reasons, please contact Count support. ### Import SQL files URL: https://learn.count.co/analytics-engine/cells-overview/import-sql-files Go from nasty, nested SQL to a clean, clear DAG. Use these step-by-step instructions to see how to use an existing SQL statement in Count, and visualize it as a connected DAG of cells. ### 1. Copy the query into your clipboard Copy directly from your favorite IDE. Count can only handle SELECT and WITH statements. If you try to run any CREATE, UPDATE, or DELETE statements, they will not be executed. ### 2. Paste into a new, blank cell Paste the query into a new cell. This query will run as expected, but it's strongly suggested to turn that 1 query into a DAG of connected cells. ### 3. Click to explode CTEs to cells Clicking the explosion button will automatically take your CTEs and represent them as connected cells. This makes it easier to understand your query, debug, and communicate with others. ### Referencing other cells URL: https://learn.count.co/analytics-engine/cells-overview/referencing-other-cells The real magic of cells. You can query other cells in SQL just as easily as you can a database. Regardless of the cell type, under the hood each cell is a table with columns. Just use the same syntax to reference a cell by name: Cells can have any name - remember to escape the cell name appropriately. Accepting a cell name using autocomplete will perform this step automatically. If you are ever unsure what columns exist in a cell, search for the cell name in the data bar. ### SQL formatting URL: https://learn.count.co/analytics-engine/cells-overview/sql-formatting How to lint your SQL for free. In the cell controls in the right-hand sidebar, you'll see an option to Format SQL. This will indent and add appropriate spacing to your query, based on the dialect of SQL for your database. (It won't edit capitalization.) ### Jinja templating URL: https://learn.count.co/analytics-engine/cells-overview/jinja-templating Putting data into words Jinja is a templating library written in Python, traditionally used for rendering HTML web pages. However, the jinja library can be used to generate any type of text, and in Count you can use it in SQL cells to write queries. Jinja expressions are enclosed in curly braces and support a subset of Python syntax, so compiling {{ 1 + 1 }} (for example) would generate 2. ## How jinja templating works When you include Jinja delimiter tags in a SQL cell (i.e. any of {{, }}, {%, %}, {#, #}), Count will attempt to compile the cell text as a jinja template before executing the cell. To view the compiled SQL that is actually executed, click the Show compiled SQL button in the design bar: Jinja templates are local to each cell, so variable and macro definitions are not shared between cells. When writing templates in SQL cells, all jinja functionality is available including: ## For loops Loop over any Python iterable and execute the expression in the body of the loop: ## If expressions Return different text depending on the result of some boolean value: ## Set expressions Declare a local variable and use it in subsequent expressions: ## Macros Define a function that can be called from subsequent expressions: ## Additional functionality provided by Count Count provides several helper functions in addition to the standard Jinja functionality. Read more about these helper functions from the documentation available through the cell autocomplete: ## ref The ref macro formats strings as SQL identifiers, adding delimiter characters and escaping as required by your database: If the source for this cell has a dbt connection, then the ref() macro can also reference models. ## cells The cells variable can be used to access the value of control cells without the requirement to use subqueries or joins - the control cell value is compiled directly into the SQL query: Control cell values are formatted as literals by default. To access the string value of a control cell more generally, use the Jinja string() filter, for example: ## literal / identifier / raw filters These filters are provided by Count to format control cell values appropriately for your database: It is currently only possible to format the values of control cells using these filters. ## Additional functionality for dbt If the current source has a dbt integration connected, then the available functionality in jinja is increased to include: - All built-in dbt APIs and macros - Any macros defined in your dbt project Explore these additional options using autocomplete while focussed within a Jinja block. ## When to use Jinja When writing queries, it is recommended to use plain SQL as much as possible for maximum portability and clarity. However, there are some cases where using Jinja is preferable or required. Avoiding subqueries Some databases restrict the use of too many subqueries, which can make it difficult to use control cells effectively. In this case it is possible to remove subqueries by switching to Jinja. For example, if your SQL looks like: then change it to: If your control cell is a multiple select, note that the compiled SQL does not contain any parentheses, so the SQL you write may look like: ## Dynamic query structure Some manipulations are impossible in SQL, such as dynamically changing the number of selected columns or the tables in the FROM clause. In these cases it is possible to use jinja templating instead: --- # Troubleshooting & FAQs Common questions and how to get the best from Count. ## Troubleshooting URL: https://learn.count.co/troubleshooting-faqs/troubleshooting Troubleshooting guide ## Quick Diagnostic Steps Try these steps to resolve common issues: Connection & Loading Issues Symptoms: "Failed to connect to Count servers", cells stuck loading Try these first: - Disable VPN - VPN connections can interfere with Count's ability to connect to our servers - Add Safe Mode to URL - Add ?safeMode=true to your canvas URL (e.g., count.co/canvas/abc123?safeMode=true) to load without executing cells. This helps diagnose if the issue is with cell execution vs. loading. - Try a different browser - If using Safari, try Chrome or Firefox to rule out a browser-specific issue. Cells stuck in loading - If caching is enabled, refresh the page - A simple browser refresh can clear temporary connection issues. Canvas is offline - If your connection to the internet is unstable or broken you might see a cloud appear in your avatar in the canvas. Check that your internet connection is stable. If a spinner is loading infinitely, contact support with the cell link (right-click on the cell > Copy as > Copy link) and share some context around what you were trying to do, whether there is jinja in the source cell and any other information that could help us identify the root cause of the problem. Performance & Memory Issues Symptoms: Canvases running slowly, cells taking forever to execute, browser becoming unresponsive Check your performance: - Open the canvas Cell Results - Click the cell status icon in the data panel on the left to see which cells are consuming the most resources - Click on column headers to sort the data and look for: - Queries returning very large datasets (500k+ rows) - Long execution time - Long extract time Quick fixes: - Add a Server -> Browser limit (to 10,000, for example) if you have set Database -> Server to Unlimited. - Add LIMIT clauses to queries - Use filters to reduce data volume - Optimize your heaviest cells first (check cell status icon for size) - Use scheduled refreshes instead of real-time queries for dashboards Cell Execution & "Waiting for Upstream Cell" Errors Symptoms: "No cached results for upstream cell", cells stuck waiting, dependency issues Most common fix: - Refresh manually - Click the refresh icon on the problem cell If that doesn't work: - Check upstream cells - Make sure all parent cells have executed successfully - Check for heavy database load - If manually rerunning fixes it, the issue is often database performance. Check the Canvas Cell Results and optimize your heaviest queries. For SQL cells specifically: - Verify whether the cell is running on your DWH or DuckDB and ensure you’re using the correct SQL syntax - Check that referenced tables/columns exist and the schema hasn’t changed Permission & Access Issues Symptoms: Can't edit canvas, data sources not showing, "permission denied" errors Canvas Permissions: Canvas permissions are separate from workspace access. Being a workspace admin/owner doesn't automatically give you edit rights to all canvases. To check/fix: - Open the canvas Share menu (top right) - Check if the canvas uses "Explicit permissions" or "Inherits from project/workspace" - If explicit permissions are set, the canvas owner needs to grant you edit access Data Source Permissions: - You need admin permissions on a connection to refresh the schema - Your workspace admin needs to grant you access in the Data Sources page Slack Integration Issues Symptoms: New Slack channels not appearing, alerts not working For new channels: - In Slack, type /invite in the new channel - Invite the Count app - For setting up alerts in that channel, use /count subscribe in the Slack channel - This works for both public and private channels To refresh your Slack connection: - Click your avatar (top right in Count) - Go to User Settings - Scroll down and click "Reauthorize Slack" Visualization & Chart Issues Symptoms: Charts not displaying correctly, filters not working, dropdown controls not refreshing charts Common fixes: - Dropdown/control not triggering refresh? - Contact support with links to both the control cell and the affected downstream cell. You can get a cell link by right clicking the cell, selecting copy as and copy link - Labels overlapping or cut off? - Increase chart height - Reduce number of data points displayed Understanding workspace styles: When you publish a color palette to your workspace, charts using that palette stay linked to it. If you update the workspace palette, all linked charts update automatically. To maintain color consistency across charts: - Keep one "source-of-truth" canvas with your shared styles - When you want to update colors workspace-wide, update them on this canvas - Click "Publish to workspace" and overwrite the existing workspace palette (don't delete and recreate - this breaks the link) - All charts using that workspace palette will update automatically If colors changed unexpectedly: Someone may have overwritten your workspace palette. Check which canvas the workspace style was originally published from (this is where future updates should happen to maintain consistency). For individual chart colors: You can override workspace styles on individual charts, but they won't update when the workspace palette changes. Data Type & Formatting Issues Symptoms: Dates showing as numbers, NULL showing as "N/A", wrong data types in charts Solutions: - CSV uploads: Count infers data types - you may need to cast them in SQL (e.g., CAST(column AS DATE)) - NULL values in multi-select filters: - The issue: When you create a multi-select control on a column with NULL values, they don’t appear in the dropdown. - The fix: In your upstream SQL cell, use COALESCE() to convert NULLs to a specific value: This converts NULL values to an actual string value (like "Unknown" or "Not Set") that the multi-select filter can properly handle. Canvas & Dashboard Behavior Dashboard state: When locked, canvases don't save updates to control cell values - each viewer uses the canvas in their own session. When unlocked, control cell changes are maintained and visible to all users. To share a locked canvas specific values in the control cells, go to the share menu in the top right corner and select 'Copy view link' ## We're here to help. Contact us immediately for: - 🚨 Bugs affecting multiple users/canvases - 🚨 Connection errors that persist after trying the above - 🚨 Questions about billing/plan changes Before you reach out, it can really help us to include: - Canvas/dashboard URL - For cell issues: Right-click the cell → Copy as → Copy link and send us that link - Screenshot of any error messages and for cell error messages right click, copy the debug code and share it with us - What you were trying to do when the issue occurred and an approximate timestamp - Browser and OS version - Whether the issue is reproducible How to get in touch: - Slack: If you have a shared Slack channel with our team, that's the fastest way to get help - Support: Use the chat widget in Count (click the '?' in the bottom right-hand corner of the screen). - Email us at support@count.co ## Count FAQs URL: https://learn.count.co/troubleshooting-faqs/count-faqs Questions. Answers. How do I roll out self-serve AI analytics safely? Start by setting context at the right level: workspace for organization-wide rules, project for team-specific logic, so agents give consistent, checkable answers before you open things up more broadly. Test any new rule in a canvas first and refine it until the agent responds the way you want, then promote it up. For business users, start with a limited audience and expand as you see the agent's answers hold up consistently over time. Data users can move faster than this, since they're able to check the agent's queries and workings directly rather than relying on trust alone. Combined with project-level permissions and telemetry, teams can self-serve with confidence, and you can see exactly how it's being used as adoption grows. Can I see what my AI agents are actually doing? Yes. Every workspace has telemetry giving you an always-on view of agent activity: who's been where, what's been queried, and what your agents have been doing on your behalf. This sits alongside Count's permissions and project structure, so you always know not just who can access what, but what's actually happening day to day. Can I use Count from tools I already have, like Slack or Claude? Yes. Count is built to be interoperable, so the trusted context and analysis you build in Count works wherever your team already does. Connect through Count's MCP server to use Count from agentic tools like Claude or Cursor, call the public API to run analyses or sync context from your own workflows, or bring Count's agent directly into Slack. Wherever the question gets asked, the answer stays consistent. Does Count have it's own database I can lean on? Will it save me lots of money on data warehouse costs? Yes, and yes. Most of an agent's analysis runs on Count's own fast in-memory engine, DuckDB, rather than your data warehouse, cutting warehouse costs from agents by up to 80%. Your warehouse is still there when you need its full power, but the bulk of day-to-day querying doesn't have to touch it. Does Count have a semantic layer? Yes. Count Metrics is an open, version-controlled semantic layer for pinning down definitions precisely: business metrics, complex SQL, and repetitive joins, defined once and reused everywhere. Agents build directly on top of it at runtime, so the same trusted definitions show up in every analysis rather than being reinvented each time. Is Count secure? Yes. Count is SOC 2 and GDPR compliant on every plan, with HIPAA compliance, SSO, SCIM provisioning, and data residency options available on Enterprise. Within a workspace, a project-based permission hierarchy lets you scope data and context to the right people and agents, and telemetry gives you an always-on view of what's actually happening. You can read more in our trust report and security overview. What kind of data can I connect? Count connects to your data wherever it lives: Warehouses and databases (live or snapshot): - Amazon Athena - Azure Synapse - Google BigQuery - Databricks - MySQL - PostgreSQL - Amazon Redshift - Snowflake - Microsoft SQL Server Internal tools: CRM records, support tickets, shared drives, and anything else reachable via MCP. Files: - CSVs (upload or drag to the canvas) The web: let the agent search for public data and context when it needs it. Other: - Use Python cells to call external APIs directly Can I query multiple databases in the same canvas? Yes. You can query multiple databases and CSV files in the same canvas. You can also use Python and SQL together and reference results from one in the other, so a SQL cell can build on a Python cell and vice versa. How much does Count cost? Check out our pricing page for all the pricing details. How long is the trial period? Can I get an extension? When you join Count you'll have a free 2-week trial in which you can access all the features and have unlimited users and canvases. If you want to extend your trial or chat, send us a note at hello@count.co How are other companies using Count? You can see a wide range of canvas examples and templates on the Gallery section of our website. We also regularly showcase how companies are using Count in Company Spotlights and webinars on our blog. Is there a community? Yes, we have a growing Slack community of fellow Count users. You can join us here.