diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/1.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/1.png deleted file mode 100644 index 726cde47..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/1.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/10.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/10.png deleted file mode 100644 index a88d5d8b..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/10.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/2.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/2.png deleted file mode 100644 index 7087109c..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/2.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/3.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/3.png deleted file mode 100644 index aae562bf..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/3.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/4.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/4.png deleted file mode 100644 index 85d1e24d..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/4.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/5.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/5.png deleted file mode 100644 index ce0d7728..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/5.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/6.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/6.png deleted file mode 100644 index b7b3cd01..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/6.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/7.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/7.png deleted file mode 100644 index b053ded8..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/7.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/8.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/8.png deleted file mode 100644 index 3cf0e617..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/8.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/9.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/9.png deleted file mode 100644 index 3aff50c3..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/9.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/caret.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/caret.png deleted file mode 100644 index 13a132ab..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/caret.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/closeview.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/closeview.png deleted file mode 100644 index d0fbb0e4..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/closeview.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/crane.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/crane.png deleted file mode 100644 index 225ecf3f..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/crane.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/facebook.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/facebook.png deleted file mode 100644 index fa3f0e02..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/facebook.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/greencheckbox.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/greencheckbox.png deleted file mode 100644 index 69cb876e..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/greencheckbox.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/heart_icon.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/heart_icon.png deleted file mode 100644 index bff9ea90..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/heart_icon.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/horizonalline.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/horizonalline.png deleted file mode 100644 index 7c49d872..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/horizonalline.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/linkedin.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/linkedin.png deleted file mode 100644 index d1a0636d..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/linkedin.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_1.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_1.png deleted file mode 100644 index b289eb20..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_1.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_10.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_10.png deleted file mode 100644 index 41a0e3e2..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_10.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_11.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_11.png deleted file mode 100644 index 67d941bc..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_11.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_12.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_12.png deleted file mode 100644 index 88852ff8..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_12.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_13.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_13.png deleted file mode 100644 index a1530721..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_13.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_14.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_14.png deleted file mode 100644 index 2444a081..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_14.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_15.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_15.png deleted file mode 100644 index 7fbd7801..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_15.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_16.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_16.png deleted file mode 100644 index 5fe2661e..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_16.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_17.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_17.png deleted file mode 100644 index f6701c86..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_17.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_18.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_18.png deleted file mode 100644 index 75488882..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_18.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_19.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_19.png deleted file mode 100644 index 6bba1a83..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_19.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_2.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_2.png deleted file mode 100644 index f89636b3..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_2.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_20.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_20.png deleted file mode 100644 index 16ab3dfb..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_20.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_3.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_3.png deleted file mode 100644 index f0353c69..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_3.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_4.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_4.png deleted file mode 100644 index 59798c51..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_4.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_5.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_5.png deleted file mode 100644 index 71bef40d..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_5.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_6.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_6.png deleted file mode 100644 index 0223bc98..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_6.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_7.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_7.png deleted file mode 100644 index a17f3732..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_7.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_8.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_8.png deleted file mode 100644 index 308e58bc..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_8.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_9.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_9.png deleted file mode 100644 index ad4a6717..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/pq_9.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/sigma_footer.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/sigma_footer.png deleted file mode 100644 index df51d771..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/sigma_footer.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/twitter.png b/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/twitter.png deleted file mode 100644 index 5a827d72..00000000 Binary files a/site/sigmaguides/embedding_12_parameterized_queries_v3/assets/twitter.png and /dev/null differ diff --git a/site/sigmaguides/embedding_12_parameterized_queries_v3/embedding_12_parameterized_queries_v3.md b/site/sigmaguides/embedding_12_parameterized_queries_v3/embedding_12_parameterized_queries_v3.md deleted file mode 100644 index a4b2d56d..00000000 --- a/site/sigmaguides/embedding_12_parameterized_queries_v3/embedding_12_parameterized_queries_v3.md +++ /dev/null @@ -1,469 +0,0 @@ -author: pballai -id: embedding_12_parameterized_queries_v3 -summary: embedding_12_parameterized_queries_v3 -categories: Embedding -environments: web -status: published -feedback link: https://github.com/sigmacomputing/sigmaquickstarts/issues -tags: default -lastUpdated: 2024-05-21 - -# Embedding 12: Parameterized Queries - -## Overview -Duration: 5 - -This QuickStart introduces Sigma embedding using parameterized queries. - -Parameterized queries are especially useful when each embedded customer has their own database with the same schema. - -While there are various ways to store customer data, this pattern is fairly common. - -To accomplish this in Sigma, we’ll use queries that leverage custom user attributes. - -### How it works -End users are authenticated by the parent application. When the user navigates to a parent page containing embedded Sigma content, the parent sends a request to Sigma via the embed API, containing user attributes that specify the database and schema names. Sigma parses that request, and applies the user attributes to the SQL query. The query is then evaluated by Sigma and, if needed, sent to the cloud data warehouse. - -How Sigma performs calculations is beyond the scope of this QuickStart, but covered in-depth in the QuickStart [Sigma's Query Engine.](https://quickstarts.sigmacomputing.com/guide/developers_sigma_calculations/index.html?index=..%2F..index#0) - -This differs from other options Sigma offers for common architectural patterns. - -Other options include: - -[Embedding 05: Multi-tenancy]() - -[Embedding 07: Dynamic Role Switching with Snowflake]() - -In this QuickStart, we will use the local host application we created in [Embedding 01: Getting Started](https://quickstarts.sigmacomputing.com/guide/embedding_03_secure_access/index.html?index=..%2F..index#0) - - - -For more information on Sigma's release strategy, see [Sigma product releases](https://help.sigmacomputing.com/docs/sigma-product-releases) - -If something is not working as you expected, here's how to [contact Sigma support](https://help.sigmacomputing.com/docs/sigma-support) - -### Target Audience -Semi-technical users who will be aiding in the planning or implementation of Sigma with embedding. No SQL or technical data skills are needed to complete this QuickStart. It does assume some common computer skills like installing software, using Terminal, navigating folders and copy/paste operations. - -### Prerequisites - - - - - - - - - -![Footer](assets/sigma_footer.png) - -## Typical use cases -Duration: 20 - -Sigma supports the most common multi-tenant architectures, which are widely used to offer secure portal access with proper data separation. - -The most common examples of this are: - -**1: One Snowflake account with per-customer databases:**
-Database names are different, but schema names are the same. - -**2: One Snowflake account with a single database and per-customer schemas:**
-Database and schema names are different. - -**3: Two Snowflake accounts with similarly structured databases and/or schemas, but different names:**
-This requires the previously mentioned connection-swapping user attribute along with custom user attributes for database and schema names. - -The core design pattern, based on custom user attributes, offers flexibility to match a variety of architectural models. - -While we’ve outlined three common use cases, the fundamental design pattern remains the same. For this QuickStart, we’ll focus on use case #2, as the steps are largely the same for the other two, with only minor differences. - -![Footer](assets/sigma_footer.png) - - -## One Snowflake account, per customer database and schema -Duration: 20 - -Imagine Sigma content embedded in a SaaS application used by multiple clients. - -Each client accesses similar types of data (e.g., store sales), all stored in the same Snowflake account. - -Database and schema names reflect each client’s name. - -For this demonstration, we’ll assume the SaaS provider is a national retail distributor with clients selling goods across U.S. regions. - -The distributor wants to embed Sigma into their client portal. - -They prefer a shared dashboard to simplify training, support, and development as new clients are onboarded. - -In this example, we’ll use two clients: `Client_A` and `Client_B`. - -Each client has a `STORE_SALES` table with the same structure, but their data is client-specific. - -To demonstrate this setup, we’ll use our trial Snowflake account to create per-customer databases and schemas. - - - -![Footer](assets/sigma_footer.png) - - -## Snowflake Configuration -Duration: 20 - -Use the following Snowflake script to automate creation of roles, databases, schemas, and sample data. - -Log into Snowflake as `ACCOUNTADMIN`. - -Open a new `SQL Worksheet`. - -The script below creates roles for `Client_A` and `Client_B`, sets up their databases and schemas, grants the required permissions, and inserts sample data into their `STORE_SALES` tables. - -It also creates a default client (`Client_Default`) with a table containing a single row of dummy data. This will serve as the default in our later Sigma configuration. This ensures that if the parent application fails to send database and/or schema values, Sigma falls back to the default without exposing other client data. - - - -Copy and paste this code into the worksheet: -```code --- Use the ACCOUNTADMIN role and COMPUTE_WH warehouse -USE ROLE ACCOUNTADMIN; -USE WAREHOUSE COMPUTE_WH; - --- Step 1: Create Roles -CREATE OR REPLACE ROLE Client_A_Role; -CREATE OR REPLACE ROLE Client_B_Role; -CREATE OR REPLACE ROLE Client_Default_Role; - --- Step 2: Create Databases and Schemas -CREATE OR REPLACE DATABASE Client_A_DB; -CREATE OR REPLACE SCHEMA Client_A_DB.Client_A_Schema; - -CREATE OR REPLACE DATABASE Client_B_DB; -CREATE OR REPLACE SCHEMA Client_B_DB.Client_B_Schema; - -CREATE OR REPLACE DATABASE Client_Default_DB; -CREATE OR REPLACE SCHEMA Client_Default_DB.Client_Default_Schema; - --- Step 3: Create Tables and Insert Sample Data - --- Client_A -CREATE TABLE Client_A_DB.Client_A_Schema.STORE_SALES ( - sale_id INT, - sale_date DATE, - store_id INT, - amount DECIMAL(10, 2) -); - -INSERT INTO Client_A_DB.Client_A_Schema.STORE_SALES (sale_id, sale_date, store_id, amount) VALUES -(1, '2024-01-01', 100, 100.00), -(2, '2024-02-02', 200, 200.00), -(3, '2024-03-03', 300, 300.00), -(4, '2024-04-04', 400, 400.00), -(5, '2024-05-05', 500, 500.00); - --- Client_B -CREATE TABLE Client_B_DB.Client_B_Schema.STORE_SALES ( - sale_id INT, - sale_date DATE, - store_id INT, - amount DECIMAL(10, 2) -); - -INSERT INTO Client_B_DB.Client_B_Schema.STORE_SALES (sale_id, sale_date, store_id, amount) VALUES -(1, '2024-06-06', 600, 600.00), -(2, '2024-07-07', 700, 700.00), -(3, '2024-08-08', 800, 800.00), -(4, '2024-09-09', 900, 900.00), -(5, '2024-10-10', 1000, 1000.00); - --- Client_Default -CREATE TABLE Client_Default_DB.Client_Default_Schema.STORE_SALES ( - sale_id INT, - sale_date DATE, - store_id INT, - amount DECIMAL(10, 2) -); - -INSERT INTO Client_Default_DB.Client_Default_Schema.STORE_SALES (sale_id, sale_date, store_id, amount) VALUES -(1, '2024-01-01', 0, 0.00); - --- Step 4: Grant Permissions - --- Client_A -GRANT USAGE ON DATABASE Client_A_DB TO ROLE Client_A_Role; -GRANT USAGE ON SCHEMA Client_A_DB.Client_A_Schema TO ROLE Client_A_Role; -GRANT SELECT ON ALL TABLES IN SCHEMA Client_A_DB.Client_A_Schema TO ROLE Client_A_Role; - --- Client_B -GRANT USAGE ON DATABASE Client_B_DB TO ROLE Client_B_Role; -GRANT USAGE ON SCHEMA Client_B_DB.Client_B_Schema TO ROLE Client_B_Role; -GRANT SELECT ON ALL TABLES IN SCHEMA Client_B_DB.Client_B_Schema TO ROLE Client_B_Role; - --- Client_Default -GRANT USAGE ON DATABASE Client_Default_DB TO ROLE Client_Default_Role; -GRANT USAGE ON SCHEMA Client_Default_DB.Client_Default_Schema TO ROLE Client_Default_Role; -GRANT SELECT ON ALL TABLES IN SCHEMA Client_Default_DB.Client_Default_Schema TO ROLE Client_Default_Role; - --- Step 5: Grant Permissions to ACCOUNTADMIN -GRANT SELECT ON ALL TABLES IN SCHEMA Client_A_DB.Client_A_Schema TO ROLE ACCOUNTADMIN; -GRANT SELECT ON ALL TABLES IN SCHEMA Client_B_DB.Client_B_Schema TO ROLE ACCOUNTADMIN; -GRANT SELECT ON ALL TABLES IN SCHEMA Client_Default_DB.Client_Default_Schema TO ROLE ACCOUNTADMIN; - -GRANT USAGE ON WAREHOUSE COMPUTE_WH TO ROLE ACCOUNTADMIN; - --- Step 6: Replace "YOUR_SIGMA_USER" with your Snowflake user with ACCOUNTADMIN role -GRANT ROLE Client_Default_Role TO USER YOUR_SIGMA_USER; -``` - - - -Run the script. Once complete, you should see the message `Statement executed successfully.` - -In the `Databases` tab, you’ll see the new tables: - - - -![Footer](assets/sigma_footer.png) - - - - - -## Sigma Configuration -Duration: 20 - -Log into Sigma as `Administrator`. - -### Create teams -Navigation to `Administration` > `Teams` and create add the `CLIENT_A` and `CLIENT_B` teams: - - - -No need to assign anyone to these teams now. - - - -### Create custom user attributes
-We need to create a few attributes that will serve as placeholders for values that will be passed from the host application at runtime. - -Navigate to `Administration` > `User Attributes` and click `Create Attribute`. - -Give the attribute the name `Client_DB`, set the default value to `Client_Default_DB` and click `Create`: - - - -Repeat the process, creating new a attribute for `Client_Schema`, taking care to assign the expected default; `Client_Default_Schema`. - -Repeat the process one more time, creating new a attribute for `Client_Role`, taking care to assign the expected default; `Client_Default_Role`. - -### Create Connection to Snowflake:
-Create a new connection in `Administration` > `Connections` and name it`Parameterized Queries QuickStart`. - -Configure the rest of the connection as shown below, adjusting for your Snowflake account and selecting `Client_Role` from the list menu: - - - -Click `Save.` Sigma will validate the connection, warning if there are any errors. - -Click the `Browse connection` button: - - - -Make sure you can see all the client database/schema: - - - -### Create the workbook -Click the `Explore` button to open the `STORE_SALES` table in a new Sigma workbook. It does not matter if you were browsing the `Client_A` or `Client_B` connection. - -Use the `Save As` button to create the new workbook named `Embedding 12: Parameterized Queries`. - - - -It is really great that Sigma can just launch a connection to data directly into a familiar spreadsheet interface, creating optimized SQL on-the-fly for us in seconds. - - - -However, we want to have a single workbook that provides all clients a common interface, using each clients data only. - -The table on this page does not do that, so lets delete it: - - - -To accomplish that, we need to create a table based on parameterized SQL instead. - -Using the `Element bar`, click `Data` > `Table` and `SQL`: - - - -Select our new `Embedding 12: Parameterized Queries` connection: - - - -We are now able to create a custom SQL statement to return data instead of Sigma doing it for us. We will use this to create a parameterized query. - -Copy and paste this code and click the `Run` button: -```code -SELECT * FROM CLIENT_A_DB.CLIENT_A_SCHEMA.STORE_SALES -``` - -While our query is not yet parameterized, this verifies that we can retrieve data as expected: - - - -Now replace the code to use our user attributes instead: -```code -SELECT * FROM {{#raw system::CurrentUserAttributeText::Client_DB}}.{{#raw system::CurrentUserAttributeText::Client_Schema}}.STORE_SALES -``` - -We are present with the single row of data from the `Client_Default_DB` table: - - - -Recall that when we created the user attributes for `Client_DB` and `Client_Schema` we set default values. This is why we are seeing data still, instead of a SQL error. - -It may also be nice to know which user is accessing data when we test the embed later. This is easy enough to do. - -Add a new `Text` element from the `UI` element bar group and configure it by typing `=CurrentUserEMail()` and clicking the : - - - -At this point, the workbook looks like this: - - - -Click `Publish`. - -### Share with teams -To be able to test this workbook, we need to share it with the two teams. - -Add the `CLIENT_A` and `CLIENT_B` teams. Set the permission to `Can View` and select `Share`: - - - -### Embed URL - -Open the workbook's menu and click `Go to published verion`: - - - -Copy the URL from the browser and store it in a text file; we will use that later. - -## Configure and Test -Duration: 5 - -In the QuickStart [Embedding 01: Getting Started](https://quickstarts.sigmacomputing.com/guide/embedding_01_prerequisites/index.html?index=..%2F..index#0) we deployed a host application locally. - -For testing, we’ll use the pre-built page that demonstrates this approach. - -In VSCode, open a new Terminal session inside the `embedding_qs_series` project and run the following command: - -```code -npm start -``` - - - -Now edit the `.env` file to update a few values. - -The `CLIENT_ID` and `SECRET` from the Getting Started QuickStart should still be present and working. If they aren’t configured, revisit the Getting Started QuickStart to complete that step. - -In the `# QS: parameterized_queries` section, we need to configure the values below, using the URL saved earlier for the `PARAMETERIZED_QUERIES_BASE_URL` value: - -```code -PARAMETERIZED_QUERIES_BASE_URL= -PARAMETERIZED_QUERIES_EMAIL=sales_person@client_a.com -PARAMETERIZED_QUERIES_ACCOUNT_TYPE=View -PARAMETERIZED_QUERIES_TEAMS=Client_A - -UPARAMETERIZED_QUERIES_ua_Client_Role=Client_A_Role -PARAMETERIZED_QUERIES_ua_Client_Schema=Client_A_Schema -PARAMETERIZED_QUERIES_ua_Client_DB=Client_A_DB -``` - -Save the `.env` file. - - - -In a browser, open: -```code -http://localhost:3000/parameterize_queries/?mode=parameterize_queries -``` - -The table loads with the Snowflake data for `Client_A` and the user attributes that were passed are shown in the left sidebar: - - - -This configuration uses Snowflake’s role-based access control to enforce data-level security. - -Embed users are authenticated by the host application, which then passes user attributes to Sigma via the embed API. Embed users are automatically added to Sigma and assigned to a team based on instructions from the host application. - - - -### Switch users - -To simulate a different user, update the `.env` values for `Client_B`: - -```code -PARAMETERIZED_QUERIES_EMAIL=sales_person@client_b.com -PARAMETERIZED_QUERIES_ACCOUNT_TYPE=View -PARAMETERIZED_QUERIES_TEAMS=Client_B - -PARAMETERIZED_QUERIES_ua_Client_Role=Client_B_Role -PARAMETERIZED_QUERIES_ua_Client_Schema=Client_B_Schema -PARAMETERIZED_QUERIES_ua_Client_DB=Client_B_DB -``` - -Save the file and refresh the browser. - -You should now see only `Client_B` data: - - - -We can now deploy a Sigma dashboard that is shared across multiple clients, ensuring per-client data isolation through parameterized queries in Sigma. - -![Footer](assets/sigma_footer.png) - - -## What we've covered -Duration: 5 - -In this QuickStart, we learned how to set up Sigma embedding using parameterized queries with Snowflake, and explored the use cases where this approach is most useful. - -**Additional Resource Links** - -[Blog](https://www.sigmacomputing.com/blog/)
-[Community](https://community.sigmacomputing.com/)
-[Help Center](https://help.sigmacomputing.com/hc/en-us)
-[QuickStarts](https://quickstarts.sigmacomputing.com/)
- -Be sure to check out all the latest developments at [Sigma's First Friday Feature page!](https://quickstarts.sigmacomputing.com/firstfridayfeatures/) -
- -[](https://twitter.com/sigmacomputing)  -[](https://www.linkedin.com/company/sigmacomputing)  -[](https://www.facebook.com/sigmacomputing) - -![Footer](assets/sigma_footer.png) - - diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC1.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC1.png index 31609489..208034a3 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC1.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC1.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC10.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC10.png index d18131d9..35d3f27c 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC10.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC10.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC10b.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC10b.png index 9f37c7b4..e15f98c0 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC10b.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC10b.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC10c.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC10c.png index 739149ac..02186ea5 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC10c.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC10c.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC12.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC12.png index 240b8c91..16d1fda3 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC12.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC12.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC14.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC14.png index 9fa73c6c..42cf2167 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC14.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC14.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC14a.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC14a.png index 29c3d9cf..42d07935 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC14a.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC14a.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC14c.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC14c.png new file mode 100644 index 00000000..98559000 Binary files /dev/null and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC14c.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC16.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC16.png index 8dcdc967..22a7c5bf 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC16.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC16.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC17.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC17.png index c63ad2c0..5ab3a990 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC17.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC17.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC18.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC18.png index 0ae7ba5c..e121d489 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC18.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC18.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC18a.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC18a.png new file mode 100644 index 00000000..ad2d22bb Binary files /dev/null and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC18a.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC19.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC19.png index 2af7d037..7c216921 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC19.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC19.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC1a.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC1a.png new file mode 100644 index 00000000..b752d475 Binary files /dev/null and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC1a.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC1b.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC1b.png new file mode 100644 index 00000000..75c66be6 Binary files /dev/null and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC1b.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC1c.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC1c.png new file mode 100644 index 00000000..7c73f205 Binary files /dev/null and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC1c.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC1d.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC1d.png new file mode 100644 index 00000000..87b2e9e9 Binary files /dev/null and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC1d.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC2.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC2.png index dfaf38c0..c6a757a0 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC2.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC2.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC20.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC20.png index 9117f20b..08f9772b 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC20.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC20.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC20a.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC20a.png new file mode 100644 index 00000000..3355b563 Binary files /dev/null and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC20a.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC20b.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC20b.png new file mode 100644 index 00000000..469db3b5 Binary files /dev/null and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC20b.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC21a.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC21a.png index 7cb535cc..c85e3bf2 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC21a.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC21a.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC21c.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC21c.png index 3fcb2142..043b8b58 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC21c.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC21c.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC21d.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC21d.png index 9a96603b..df21bc23 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC21d.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC21d.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC21f.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC21f.png index 595b57d2..06b7cf9b 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC21f.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC21f.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC22.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC22.png index 64361f4b..caa62841 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC22.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC22.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC22a.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC22a.png new file mode 100644 index 00000000..a71778e5 Binary files /dev/null and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC22a.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC23.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC23.png index 757373f7..f8f81213 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC23.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC23.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC24.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC24.png index ee1a4d2e..338444b2 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC24.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC24.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC25A.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC25A.png index 726996c4..663bf1d7 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC25A.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC25A.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC27.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC27.png index ce455eaa..639420fa 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC27.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC27.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC28.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC28.png index 4767dbd4..98ebdad8 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC28.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC28.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC28a.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC28a.png new file mode 100644 index 00000000..527834df Binary files /dev/null and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC28a.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC28b.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC28b.png new file mode 100644 index 00000000..76fdcf62 Binary files /dev/null and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC28b.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC2b.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC2b.png new file mode 100644 index 00000000..659acbed Binary files /dev/null and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC2b.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC3.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC3.png index 039bd298..26435fcc 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC3.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC3.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC30.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC30.png index 7cf38b6b..8e8b1353 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC30.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC30.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC31.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC31.png index 09705fc3..fa579202 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC31.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC31.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC32.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC32.png index 485be450..46f382f2 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC32.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC32.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC33a.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC33a.png index 067a484e..a23d9019 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC33a.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC33a.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC34.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC34.png index 2b5cf2b2..45667d6b 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC34.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC34.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC34a.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC34a.png new file mode 100644 index 00000000..c2e8ca29 Binary files /dev/null and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC34a.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC35.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC35.png index 9a53ba64..cec6f6f1 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC35.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC35.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC37.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC37.png index a961ed0d..d217c337 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC37.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC37.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC38.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC38.png index 2f19bf5e..be8f8d25 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC38.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC38.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC39.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC39.png index 885b3d80..96728d9c 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC39.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC39.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC41.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC41.png index f709037a..6bba4554 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC41.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC41.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC42.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC42.png index 03c95e08..b17f4e4f 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC42.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC42.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC43.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC43.png index 81f8ffd5..59525d14 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC43.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC43.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC5.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC5.png index 6d4d3464..12ff13e1 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC5.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC5.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC56.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC56.png index c3da1d04..aec68ce6 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC56.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC56.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC57.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC57.png index 5f4f6266..f3a084cc 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC57.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC57.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC58.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC58.png index 67ff3f91..97fac0c6 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC58.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC58.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC6.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC6.png index 0ce78e3c..997ba5b3 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC6.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC6.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC8.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC8.png index 78f4a4b9..0ee89f6d 100644 Binary files a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC8.png and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC8.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC8a.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC8a.png new file mode 100644 index 00000000..0ee89f6d Binary files /dev/null and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC8a.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC8b.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC8b.png new file mode 100644 index 00000000..31754394 Binary files /dev/null and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC8b.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC9a.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC9a.png new file mode 100644 index 00000000..c0d89a8a Binary files /dev/null and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC9a.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC9b.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC9b.png new file mode 100644 index 00000000..e6cbe43c Binary files /dev/null and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC9b.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC9c.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC9c.png new file mode 100644 index 00000000..9ee56e5d Binary files /dev/null and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC9c.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC9d.png b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC9d.png new file mode 100644 index 00000000..967f2f9c Binary files /dev/null and b/site/sigmaguides/src/functions_common_date_use_cases/assets/CDUC9d.png differ diff --git a/site/sigmaguides/src/functions_common_date_use_cases/functions_common_date_use_cases.md b/site/sigmaguides/src/functions_common_date_use_cases/functions_common_date_use_cases.md index 8917d399..f51f870c 100644 --- a/site/sigmaguides/src/functions_common_date_use_cases/functions_common_date_use_cases.md +++ b/site/sigmaguides/src/functions_common_date_use_cases/functions_common_date_use_cases.md @@ -6,149 +6,188 @@ environments: web status: Published feedback link: https://github.com/sigmacomputing/sigmaquickstarts/issues tags: default -lastUpdated: 2023-03-24 +lastUpdated: 2025-06-25 # Common Date Functions and Use Cases - ## Overview Duration: 5 This QuickStart presents common challenges when working with dates. Sigma can be used to manipulate dates to get the desired results, quickly and easily. -There are many ways to solution with dates in Sigma. Not every solution is covered and you may even found a better method. Suggestions and feedback is always appreciated. +There are many ways to work with dates in Sigma. Not every solution is covered and you may even find a better method. Suggestions and feedback are always appreciated. This QuickStart assumes you have a working instance of Sigma and the connection called Sigma Sample Database. -We will use the Sigma provided `RETAIL`.`PLUGS_ELECTRONICS`.`PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA` table so that you can recreate each QuickStart Step in your own Sigma environment. - - - -For more information on Sigma's product release strategy, see [Sigma product releases.](https://help.sigmacomputing.com/docs/sigma-product-releases) +We will use the Sigma-provided `RETAIL`.`PLUGS_ELECTRONICS`.`PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA` table so you can follow along and recreate each step in your own Sigma environment. ### Target Audience -Anyone who is looking for solutions to date challenges or just want to learn new date methods. +Sigma builders looking for solutions to date challenges or who just wants to learn new date methods. ### Prerequisites -1: A computer with a current browser. It does not matter which browser you want to use.
-2: A Sigma account. - -### What You’ll Learn -How to apply Sigma functions to date challenges. -### What You’ll Build + + + -We will cover a large number of methods for working with dates in Sigma. Date logic can be confusing so we will start with the basics to show how Sigma makes the simple stuff easy and then get more complex to show how Sigma makes the hard stuff possible all through an easy to used interface. +
+ + ![Footer](assets/sigma_footer.png) -## **Basic Formatting** +## Basic Formatting Duration: 10 -Let's start simply by presenting the standard ways to alter/adjust a date column. +Let's start with the standard ways to adjust a date column. + +Log into Sigma, click `Create new` and select `Workbook`. + +From the `Element bar`, under the `Data` group, place a new `Table` on the page. -Create a new Workbook and place the `PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA` table on the page. You can just take all the columns. We are mostly interested in the Date column right now but will use the others as we add logic later. +Click `Select source` for the new table. + +Search for `Hands` and select the `PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA` table from the `RETAIL` database. + +Save the workbook as `Common Date Functions and Use Cases`. + +We’re primarily interested in the `Date` column, which is coming in 'as-is' from the warehouse: -Click on the `Date` columns down arrow and select `Truncate date`. This is one way to adjust how the Date column will be modified. +Click on the `Date` column down arrow and select `Truncate date`. This is one way to modify how the `Date` column is displayed. -If you select the `Day` option, notice that the column name is changed to `Day of Date` +If you select the `Day` option, you'll see the column name changes to `Day of Date`. + +Reset the `Date` column back to the default. You can use `Remove date truncate` from the column's menu but the `Undo` icon is faster: -Reset the Date column back the the default (use "Remove date truncate" or the back icon if you are in edit mode). + -Click on the `Date` columns down arrow and select `Format date`. This is another way to adjust how the Date column will be modified: +Click on the `Date` column down arrow and select `Format date`. This is another way to change how the `Date` column is displayed: - + Feel free to experiment with the available options, resetting to the original when done. ![Footer](assets/sigma_footer.png) -## **Custom Formatting** +## Custom Formatting Duration: 10 -Sigma supports applying custom formats to date columns. You can do this by selecting the `Date` columns menu and then `Format` and `Custom`: +Sigma supports applying custom formats to date columns. You can do this by selecting the `Date` column menu and then `Format` > `Custom`: -Setting the `Format string` to the code below will cause the popup to show you a sample of the output. This is quite useful to know your string is correct before applying it. - -```plaintext +Entering the format string below will show a sample output in the popup: +```code %a %B %d %Y ``` -[A full list of custom format strings is available here.](https://help.sigmacomputing.com/docs/define-custom-date-formats) + - +This helps confirm your format string is correct before applying it. -Feel free to experiment and then reset the `Date` column back to the default when done. +Feel free to experiment, then reset the `Date` column back to the default when done. -Another way to use custom date formatting is to apply a Function in the formula bar using one of the many `DateFormat` functions. +### The formula bar +Another way to apply custom date formatting is by using the formula bar and the `DateFormat` function. -For example, you may want to get the full month-name from a date column. +For example, you may want to get the full month name from a date column. -Create a new column and rename it `Month of Date`. +Create a new column by using the `Date` columns menu and selecting `Add new column`. Rename the new column `Month of Date`. -Place this code in the formula bar and click the checkmark (or press Enter): +To make it clear for users, rename the `Date` column to `Original_Date`. -```plaintext -DateFormat(Date([Original Date]), "%B") +Click the `Month of Date` column, enter this formula into the formula bar and press enter. +```code +DateFormat(Date([Original_Date]), "%B") ``` - +This demonstrates how to use the formula bar to apply both a function (DateFormat) and a custom format string: -Here are some others we built using the same method and there are many more possible: + + +Here are a few other examples created using the same method—many more are possible: +For more information, see [Custom format strings](https://help.sigmacomputing.com/docs/define-custom-datetime-formats#custom-format-strings) ![Footer](assets/sigma_footer.png) -## **Current / Previous Weekday** +## Current / Previous Weekday Duration: 10 -It can be useful to get the current or previous weekday when presenting data to users. For example, in the table below we have one row of data with today's date in the `Today` column. +Now that we’ve covered the basics, let’s apply what we’ve learned to a new use case. -We use this column in a Function to determine If the input date is a Monday, we show the day in the `Day Name of Today` and then the function returns the calculated `Current Weekday`. +For example, it’s often useful for users to know the `Effective Business Day` an order was placed. If an order is placed on a Saturday or Sunday, this column will show Friday as the effective day, helping analysts align reporting with standard business operations. - +Undo any changes we made to our table, and then format the `Date` column to basic `Date` format: -The Function is: -```plaintext + + +Rename the `Date` column to `Today` to make its purpose clearer to users. + +Next, we want to display the weekday name for each value in the `Today` column. + +Add a new column next to `Today`, and set its formula to: +```code +DateFormat(Date([Today]), "%A") +``` + + + + + +Now that we have the current weekday name, we can apply it to the use case. + +Add another new column next to `Day` and use the following formula: +```code DateFormat(DateAdd("day", (If(Weekday([Today]) = 7, -1, Weekday([Today]) = 1, -2, 0)), [Today]), "%A") ``` -If the input date is a Saturday, the function returns the date of the Friday immediately previous. +This formula returns the previous weekday name if today is Saturday (7) or Sunday (1); otherwise, it returns today’s name. + +Then, hide the `Today` and `Day` columns, and rename the new column to `Effective Business Day`: + + - +For more information, see [Define custom datetime formats](https://help.sigmacomputing.com/docs/define-custom-datetime-formats) -[A breakdown of this Function's parts is available here.](https://help.sigmacomputing.com/docs/dateformat) +Click `Publish`. ![Footer](assets/sigma_footer.png) -## **Time Between Dates** +## Time Between Dates Duration: 10 -It is often useful to know the elapsed time between two dates (and times). Some examples are: +s often useful to measure the time elapsed between two dates (or timestamps). Some examples are: **Call Center Support:** Call duration
**Customer Service:** Order fulfillment time
**Healthcare:** Time since last blood test
-Let's take a look at the Customer Service use case. +Let's take a look at the customer service use case. Marketing is interested in targeting customers who purchase frequently but only has a table with all orders to start with. -They want to know a few things: +They want to answer a few key questions: +We’ll continue using the `PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA` table, but this time we’ll create a child table. -Create another Workbook Page. + -The data we will use is still the `PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA` table. You can create a child of the table we used earlier of just add a new table to the Page based on it as source. We only need the columns `Customer Name` and `Date`. + -`Group` the table by `Customer Name`. +Rename the child table `Time Between Dates` and move it to a new workbook page: -Truncate the `Date` column to day: + - +Rename the new workbook page `Time Between Dates`. - +We only need a few columns including the `Today` column but that is hidden from our last section. No problem—it’s still available in the child table, and we can make it visible: -`Group` by the `Day of Date`: + - +Since we don’t need most columns in the child table, we can delete them, leaving only the `Customer Name` and `Today` columns. -Lets filter the data (to keep things simple to see as we work) for `Customer Name` = `Leah Douglas`: +Using the `Element panel`, move the `Customer Name` and `Today` columns to the top of the list and then select all others and click `Delete 21 columns`: - + -The table should now look like this: +Drag the `Customer Name` column to `GROUP BY`. - + -Add a new column by clicking the `Customer Name` menu arrow and rename it to `First Order`: +Drag the `Customer Name` column to `GROUPINGS` to create a new group. - +To simplify the view, filter the data where `Customer Name = Leah Douglas`: -For `First Order` set the formula to: + + +The table should now look like this: + + + +Add a new column next to `Customer Name` and rename it to `First_Order`. + +For `First_Order` set the formula to: ```plaintext -Min([Day of Date]) +Min([Today]) ``` -Now we will add four more columns, rename them as shown below and apply the Functions in the formula bar for each: + -```plaintext -Column: Formula: -Second Order Nth([Day of Date], 2) -Last Order Max([Day of Date]) -Days 1st to 2nd Order DateDiff("day", [First Order], [Second Order]) -Days Since Last Order DateDiff("day", [Last Order], Today()) +Now add four more columns, renaming them and applying the following formulas: + + + +For more information, see [Keyboard shortcuts: Microsoft Windows](https://help.sigmacomputing.com/docs/keyboard-shortcuts-microsoft-windows) or [Keyboard shortcuts: Mac OS](https://help.sigmacomputing.com/docs/keyboard-shortcuts-mac-os) + +```code +Column Name: Formula: +Second_Order Nth([Today], 2) +Last_Order Max([Today]) +Days_1st_to_2nd_Order DateDiff("day", [First_Order], [Second_Order]) +Days_Since_Last_Order DateDiff("day", [Last_Order], Today()) ``` -The table should now look like this (after collapsing it): +Hide the `Today` column. - +The table should now look like this: -Go ahead and turn off the filter. + -Now Marketing has the data they are requesting: +Go ahead and disable the filter. +Marketing now has the data they requested: + + + ![Footer](assets/sigma_footer.png) -## **Week over Week** +## Week over Week Duration: 10 -Sales Operations wants to know see how weekly sales numbers look compared to the previous week. +Sales Operations wants to see how weekly sales numbers look compared to the previous week. -Let's use this example to investigate using the Lead and Lag function in Sigma. These functions make this use case surprisingly simple to execute. +Let’s use this example to explore Sigma’s `Lead` and `Lag` functions. These functions make this type of comparison surprisingly easy. -In this example, we will go about getting data a different way (extra credit!). Create another Workbook Page and rename it `Week Over Week`. +In this example, we’ll approach the data a bit differently this time. Create another Workbook Page and rename it `Week Over Week`. -Add a table to the Page but this time select the `F_Sales` from the Sample Database, selecting these columns: +Add a table to the page, and this time select `F_Sales` from the `Sigma Sample Database`. - +This gives us all the sales transactions. -This gives us all the sales transactions. Now we want to join a table to this for the point of sale data. +Next, we’ll join another table to bring in point-of-sale data. -Click the menu in the F_Sales table and select `Element Source` and then `Join`: +Click the `3-dot menu` on the `F_Sales` table and select `Element Source` and then `Join`: - + -Select the table `F_Point_of_Sale`, selecting only the `Sales Amount` column. +Search for and select `F_Point_of_Sale` from the `RETAIL` schema and select only the `Sales Amount` column. - + -Now we have to decide what type of join we want and on which columns (Join Keys). +Now choose the type of join and identify the join keys (matching columns from each table). -Based on our joining the two tables against Order Number we have 100% match. Change the join to inner join and see the results. Still 100%, so in this case, either join will work. +Since we’re joining the two tables on `Order Number`, we have a 100% match. This works because every sale must have an order number, so it exists in both tables. +For more information, see [Join types](https://help.sigmacomputing.com/docs/join-types) + -Preview the data and click `Done`. We now have a table on our Page we can rename to `Week over Week Sales`. +Click Preview output. Sigma shows the tables lineage. This allows us to see how our table was constructed, which columns are selected and more. We could also join more tables from here: -Drag the `Date` column to `Groupings` and Truncate it to `Week`: + - +For more information, see [View workbook and data model data lineage](https://help.sigmacomputing.com/docs/workbook-data-lineage) + +Click `Done`, and rename the table `Week_over_Week_Sales`. -Hide the `Order Number`, `Date` and `Sales Amount` columns. +Drag the `Date` column to `Groupings` and truncate it to `Week`. -Drag the `Sales Amount` column to `Calculations`, rename it to `Weekly Sales` and set the format to `currency`: +Hide the `Order Number`, `Date` and `Sales Amount` columns: - + -Add two calculated columns (in CALCULATIONS). Rename each and set the functions as: +Drag the `Sales Amount` column to `Calculations`, rename it to `Weekly_Sales` and set the format to `currency`: -```plaintext + + +Add two calculated columns using the `+` icon in the `CALCULATIONS` panel. Rename each and set the formulas to: +```code Column: Formula: -Sales Lag 1 Week [Weekly Sales] / Lag([Weekly Sales], 1) -Sales Lead 1 Week [Weekly Sales] / Lead([Weekly Sales], 1) +Sales_Lag_1_Week [Weekly_Sales] / Lag([Weekly_Sales], 1) +Sales_Lead_1_Week [Weekly_Sales] / Lead([Weekly_Sales], 1) ``` -Set the `Lead/Lag` columns to `percentage`: +Format the `Lead/Lag` columns as percentages and sort the `Week of Date` column in descending order: - + - + -[Read more about Lead and Lag funtions.](https://help.sigmacomputing.com/docs/lead) +For more information, see [Lead](https://help.sigmacomputing.com/docs/lead) + +Sales Operations can now compare weekly sales performance at a glance. + +This use case could also be solved using Sigma’s `DateLookback` function. The `DateLookback` function returns the value of a variable at a previous point in time (or lookback period) determined by a specified date and offset. + +We will use `DateLookback` in the next section. ![Footer](assets/sigma_footer.png) -## **Year over Year** +## Year over Year Duration: 10 -Viewing data organized `Year over year by month` gives users insight on how a business is doing in use cases like seasonality. Observing year over year performance gauges if performance is improving, static, or worsening. +Viewing data organized `year over year by month` helps users understand business performance in use cases like seasonality. It allows users to see whether performance is improving, flat, or declining year over year. -We are going to move a little faster now that we learned how to work with the Sigma UI. +Now that we've learned how to navigate Sigma, we’ll move a bit faster. -Create a new Workbook Page and add the `PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA` table to it. +Since we’ll reuse the `Page 1` source, rename the page to `Data`. -Hide all columns to start. Use `Shift` and `Click` to select the first and last in the list and then click `Hide column`. +Add a new workbook page and add another child of the `PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA` table to it. -Add a new group (click the `+` to the right of `GROUPINGS` and select `Date`) +Rename the page `Year over Year` and the table to `Year_Over_Year_by_Month`. -Set the formula for the `Day of Date` column to: +Add the `Today` column back as we did in the last section. -```plaintext -DateFormat(Date([Date]), "%m") -``` -Rename this column `Month Number` and set it's sort order to `Ascending`. +Start by hiding all columns. Use `Shift + Click` to select the first and last, then click `Hide column`. - +Now we have lots of columns to work with but none are displayed: -Add a new column: + -Set it's formula to -```plaintext -DateTrunc("year", [Date]) +Add a new grouping by clicking the `+` next to `GROUPINGS` and selecting the `Today` column. + +Set the formula for the `Day of Today` column to: +```code +DateFormat(Date([Today]), "%m") ``` -Add this new column to a new group (click the `+` to the right of `GROUPINGS` and select `Year of Date`) +Rename this column `Month_Number` and set its sort order to `Ascending`. - + -Click the `-` in the `Month Number` column to collapse the table. We now have 12 months of data: +Add another `GROUPING` selecting the `Today` column again. - +Set the new column's formula to: +```code +DateTrunc("year", [Today]) +``` -Add a new column (to the right of `Year to Date`) and rename it `Monthly Sales`. Set it's formula to: +Rename the column `Year`: -```plaintext + + +Add a new calculation by clicking the `+` next to `CALCULATIONS` in the `Year` grouping, and select `New column`: +```code Sum([Quantity] * [Price]) ``` +Format the column as currency. + The table should now look similar to this (after collapsing/expanding and formatting): - + -Add a new `CALCULATION` (click the `+` to the right of `CALCULATIONS` in the `Year of Date` grouping and select `New column`) +Add a new `CALCULATION` by clicking the `+` to the right of `CALCULATIONS` in the `Year` grouping and select `New column`. - + Configure the new column as shown below: - -```plaintext -Column: Formula: -Previous Month Lead([Monthly Sales], -1) +```code +Column Name: Formula: +Previous_Year DateLookback([Monthly_Sales], [Year], 1, "year") ``` -Add another new `CALCULATION` (click the `+` to the right of `CALCULATIONS` in the `Year of Date` grouping and select `New column`) -```plaintext -Column: Formula: -Year over Year ([Monthly Sales] - [Previous Month]) / [Previous Month] +Now we can calculate the year over year percentage difference for each month. + +Add another new `CALCULATION` column to the same grouping and configure it using: +```code +Column Name: Formula: +% Change ([Monthly_Sales] - [Previous_Year]) / [Previous_Year] ``` -Set the `Year over Year` columns format to `Percentage`. +Set the column's format to `Percentage`. Now we can start to see trends in the data. +For more information, see [DateLookback](https://help.sigmacomputing.com/docs/datelookback) + +Click `Publish`. + ![Footer](assets/sigma_footer.png) -## **InDate Range** +## InDate Range Duration: 10 -The InDateRange function provides a succinct way to write calculations such as Year to Date and Last 3 Month. It also simplifies more complex calculations, making them shorter and easier to read. +The `InDateRange` function provides a succinct way to write calculations such as `last year` or `this year`. It also simplifies more complex calculations, making them shorter and easier to read. While there are other ways to solve this, let’s explore a different approach using `InDateRange`. -The InDateRange function will return True or False based on its configuration. The table can then be filtered based on a InDateRange column being true or false. +What's differnt with the `InDateRange` function is that it will return `True` or `False` based on its configuration. The table can then be filtered based on an `InDateRange` column being `True` or `False`. For example, we may want to see how sales this year compare with last year, side by side. -Create a new Workbook and rename it to InDate Range. +Create a new page and rename it to `InDate Range`. -Add the `PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA` table. +Add another child of the `PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA` table and move it to the new page. -Truncate the `Date` column to `Day`. +Rename the table `Sales_Comparison`. -Add a new column as: -```plaintext -DatePart("week", [Day of Date]) -``` +Add the `Today` column back to the table. -Rename the new column to `Week`. + -Add a new column called `Sales Amount`. +Add a new column using this configuration: +```code +Column Name: Formula: +Week DatePart("week", [Today]) +``` -Set it's formula to -```plaintext -[Price] * [Quantity] +Add another new column using this configuration: +```code +Column Name: Formula: +Sales_Amount [Price] * [Quantity] ``` Hide this column. -We will use the `InDate Range` function in several new columns. - -For each of the following new columns you add, configure them using the following: +Next, use the `InDateRange` function to create four new columns. -```plaintext -COLUMN NAME FORMULA TO APPLY TO COLUMN - -Week # DatePart("week", [Day of Date]) -isCurrent Year InDateRange([Day of Date], "current", "year") -isLast Year InDateRange([Day of Date], "last", "year") -isCurrent Quarter InDateRange([Day of Date], "to_date", "quarter") -isCurrent Month InDateRange([Day of Date], "to_date", "month") -isCurrent Week InDateRange([Day of Date], "to_date", "week") -isIN Last 2 Weeks InDateRange([Day of Date], "last", "week", 2) -TY Sales Amount SumIf([Sales Amount], [isCurrent Year]) -LY Sales Amount SumIf([Sales Amount], [isLast Year]) +For each of the following new columns, use the following configuration: +```code +Column Name: Formula: +isCurrent_Year InDateRange([Today], "current", "year") +isLast_Year InDateRange([Today], "last", "year") +This_Year_Sales_Amount SumIf([Sales_Amount], [isCurrent_Year]) +Last_Year_Sales_Amount SumIf([Sales_Amount], [isLast_Year]) ``` -The table should now look like this: +The table should now look like this. Notice that sales amount values only appear for the current and previous years. All others are null: -Next add a child PivotTable. +Instead of filtering the table to show only rows for the current and previous years, let’s use a pivot table. - +Add a child pivot table: -Configure the Pivot Table as shown: + - +Configure the pivot table as shown below and rename it `Sales - This Year vs. Last`: - + -Now that we have all these columns as part of our data there are many ways you may want to leverage them in Sigma to create interesting Period over Period style visualizations. +From here we can start to dig deeper into the analysis by calculating sales changes or adding visualizations. + +For more information, see [InDateRange](https://help.sigmacomputing.com/docs/indaterange) ![Footer](assets/sigma_footer.png) -## **Lookups - Year over Year** +## Lookups Duration: 10 -In this example we will demonstrate using data from one table in another. +In this example, we’ll demonstrate how to use data from one table in another using a Lookup. -Let's assume that there are two tables that have columns that do not exist in a third. We can use a Lookup to bring those columns over to the third table. +Imagine two tables contain useful columns that are missing from a third table. To enrich the third table, we can use a `Lookup` to bring in those missing columns. -The tables will be are joined by a pair of columns — one from each — that share common values. We call these joining columns join keys. +Lookups work by matching rows based on shared values between two columns—one from each table. These columns are known as join keys and we will simulate how this works using our existing sample data. -Columns created from a lookup can be added using the Lookup function. However, you can also add a new lookup column without explicitly writing a formula. +Add a new workbook page and place another child of the `PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA` table from the `Data` page to it. -[Click here for more information on using Lookups](https://help.sigmacomputing.com/docs/add-columns-through-lookup) +Another way to do this is to add a new `Table` from the `Element bar` and set the source as shown: -Create a new Workbook Page and add the `PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA` table to it. + -Rename the Page tab to `Lookups - Year over year`. +Rename the page `Lookups` and the table to `Regional_Sales_Performance`. -Rename this table `Regional Sales Performance - This vs. Last Year`. +Add the `Today` column back as we did in the last section. Duplicate the table using the table menu. -Rename this table `Sales This Year` +Rename this duplicated table `Sales_This_Year` -On the second table, hide all the columns leaving only `Store Name`, `Store Region`, `Store Key`, and `Date`. +On the `Sales_This_Year` table, hide all the columns leaving only `Store Name`, `Store Region`, `Store Key`, and `Today`. -Add a new column, rename it `Total Sale` and set its formula to: -```plaintext +Add a new column, rename it `Total_Sale` and set its formula to: +```code [Price] * [Quantity] ``` -The formula on the `Date` column to: - -```plaintext -DateTrunc("day", [PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA/Date]) -``` -Rename the column back to `Date` - -Your page should now look link this: +Your page should now look like this: -Let's filter this table to display orders from this year only (click on the `Date` column's drop arrow and select `Filter`): +Filter this table to show only orders from this year (click the drop-down arrow on the `Today` column and select `Filter`): - + -Back on the `Regional Sales Performance - This vs. Last Year`, we want to group on the `Store Region` column. +On the `Regional Sales Performance` table, we want to group on the `Store Region` column. -Now add a new column / Column via lookup: +Now add a new column via lookup: - + You will be prompted to set how the two tables will be joined. Use this configuration: -Now drag the new Lookup column to the `Calculations` sectrion of the `Store Region` grouping: +Now drag the new lookup column to the `Calculations` section of the `Store Region` grouping: - + -Now lets get last years sales. Duplicate the table `Sales This Year`. +Now let’s get last year’s sales. Duplicate the `Sales_This_Year` table: -Rename the table to `Sales Last Year`. +Rename the table to `Sales_Last_Year`. -Change the filter to use last year as the range. +Change the filter to use last year as the range: - + -The page should look like this now (after moving thing around to suit): +The page should now look like this (after rearranging elements as needed): -Now add another new column via Lookup (into the `Regional Sales Performance - This vs. Last Year` table) as before using the new `Sales Last Year` table. - - +Now add another lookup column to the `Regional_Sales_Performance` table, using `Sales_Last_Year` as the source. The only configuration difference is the source table as shown: - + -Drag this new column to `Calculations` and you are done. We now have last year and this year (by Store Region) with all the detail as well. +Drag this new column into the `Calculations` section—and we’re done. We now have both last year’s and this year’s sales by store region, with full detail. - + + +For more information, see [Add columns through Lookup](https://help.sigmacomputing.com/docs/add-columns-through-lookup) ![Footer](assets/sigma_footer.png) -## **InPrior Date Range** +## InPrior Date Range Duration: 10 -The InPriorDateRange function is used for calculations that look at a date range in a prior period, such as This Week Last Year. +The `InPriorDateRange` function is used to calculate values from a prior time period such as "This Week Last Year". -The results will appear as `Boolean` (true or false), and we can use that to filter rows to suit. +It returns a `Boolean` (True or False), which we can use to filter rows. -To make this go faster, open the Workbook `Lookups - Year over Year` and use `Save As` to make a copy as `InPrior Date Range`. +To speed things up, duplicate the `Lookups` page and rename the copy `InPrior_Date_Range`. -Please the new Workbook in `Edit` mode. +Rename the `Sales_This_Year` table to `Sales_In_Current_Quarter`. -Rename the `Sales This Year` table to `Sales In Current Quarter`. Do the same for the `Sales Last Year` table, to `Sales Last Year - Same Quarter`. +Also rename the `Sales_Last_Year` table to `Sales_Last_Year_Same_Quarter`. -In the `Sales In Current Quarter` table, we want to filter the data to show only the rows from last quarter. We can do that by simply using the filters control: +In the `Sales_Last_Year_Same_Quarter` table, we want to filter the data to show only the rows from last quarter. We can do that by simply using the filters control: - + -In the `Sales Last Year - Same Quarter`, add a new column called `InPriorQuarter` and set is formula to: +In the `Sales_Last_Year_Same_Quarter`, add a new column named `InPriorQuarter` and set its formula to: ```code -InPriorDateRange([Date], "quarter", "year") +InPriorDateRange([Today], "quarter", "year") ``` -This will evaluate the `Date` column and return `true` or `false` if the date is in the quarter, one year prior. +This will evaluate the `Today` column and return `true` or `false` if the date is in the quarter, one year prior. + +Next, update the table’s filters by adding a new one on the `InPriorQuarter` column and set it to show only rows where the value is `True`. -Now alter the table's filter, adding a new filter on our new column, `InPriorQuarter` and only select to see the rows where the value is `True`. Delete the filter for `Date`. +We can disable the filter for `Today` since our formula is providing the filter now: - + -Since the `Regional Sales Performance - This vs. Last Year` table uses `Lookups` to get the `Total Sale` column from each of the other two columns already, we don't have to do anything; the sales are summed and grouped already. +Since the `Regional_Sales_Performance` table already uses lookups to bring in the `Total Sale` column from both source tables, we don't have to do anything; the sales are summed and grouped already. We are done: - +Compare these values to those on the `Lookups` page—you’ll see they are significantly lower. - + -Sigma provides tools to help you understand warehouse costs, built right into the Sigma platform. - -For more information about that, [click here.](https://quickstarts.sigmacomputing.com/guide/snowflake_cost_per_query_template_setup/index.html?index=..%2F..index#0) and [here.](https://help.sigmacomputing.com/docs/snowflake-usage-templates) + ![Footer](assets/sigma_footer.png) -## **Date Calendars - The Retail 4-5-4 Calendar** +## Date Calendars - The Retail 4-5-4 Calendar Duration: 10 Companies often use table-based calendars in analytics to help address data consistency, seasonality, and planning. -In this QuickStart Step we will build a pivot table that leverages the `NRF Retail 4-5-4 Calendar` combined with our `Plugs Electronics` sample data to look at same store sales the way most retailers prefer. The same general methods apply to using any table-based calendar you may have. +In this QuickStart step, we’ll build a pivot table that leverages the `NRF Retail 4-5-4 Calendar` combined with our `Plugs Electronics` sample data to analyze same-store sales the way most retailers prefer. These same general methods apply to any table-based calendar you use. The NRF Retail 4-5-4 Calendar is a standardized retail calendar developed by the National Retail Federation (NRF) to help retailers track and analyze their sales performance. It is widely used by retailers in the United States, and it is particularly useful for businesses that operate on a fiscal year that does not align with the traditional calendar year. The calendar helps retailers plan their inventory, staffing, and marketing strategies based on historical sales data and seasonal trends. -Create a new Workbook and rename it to `Same Store Sales`. - -In this exercise we will use some Sigma functionality not yet covered to enhance your learning by creating a joined table for Plugs sales and the 4-5-4 table to that for analysis. - -Add a new Table to the Workbook. + -Navigate to the `Sigma Sample Database` / `Retail` / `Plugs_Electronics` / `Plugs_Electronics_Hands_On_Lab_Data` table: +For more information, see [NRF 4-5-4 Calendar](https://nrf.com/resources/4-5-4-calendar) - +Add a new workbook page, and this time, add the `PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA` table by selecting it from the sample database instead of the `Data` page: -Rename the table to `Plugs Same Store Sales`. + -We will need to calculate the value of each row (Order Value) since the data only has quantity and price. +Rename the page `Date_Calendar`. -Add a new column, rename it to `Order Value` and use this formula: +Rename the table to `Same_Store_Sales`. -```plaintext +Add a new column, rename it to `Order_Value` and use this formula: +```code [Quantity] * [Price] ``` -Click the `Tables` menu and select `Element Source` then `Join`: +Create a new join: - + -Navigate to the `4_5_4_CALENDAR` and select it: +Search for the `4_5_4_CALENDAR` in the `RETAIL` schema and select it: - + -We are now presented with a screen that allows us to adjust how the two tables are joined. We will need to adjust how the 4-5-4 table is joined as we want to join on the `Date` column. For this to work, we need to ensure the datatype is the same. To do that, click the 4-5-4 table (on the left) and change the `Join Keys` for **both tables** to use a custom formula. That formula is: +We are now presented with a screen that allows us to adjust how the two tables are joined. We need to adjust the join to use the `Date` and `Today` columns -```plaintext -DateTrunc("day", [DATE]) -``` +If we look closely at the join results we can see there is a mismatch; the timestamps are causing a problem: - +Joining on mismatched data types can cause issues, but Sigma supports formula-based joins to correct the issue. + +To handle the datatype issue, we will use a formula for each join key: -After making the changes, you should have many matches. It won't be 100% match as there are some values in the Plugs table that are not in the 4-5-4 table. Click `Preview Output`. + + +Apply this formula to both join keys: +```code +DateTrunc("day", [DATE]) +``` -We are presented with the data and a graphical representation of the data flow (lineage): +After making the changes, you should have many matches. It won’t be a 100% match, as some values in the Plugs table that are not in the 4-5-4 table. - +Click `Preview Output` and `Done`. -We can now create a `Child` from this table and use a `Pivot Table`: +Now, create a child of this table and select `Pivot Table` as the type: -Now we can create our pivot by dragging column name (in the Element Panel to the respective groupings, not the table) as shown below: +Rename the pivot table to `Same_Store_Sales_454_Calendar`. + +Configure the pivot table as shown below: -Rename the pivot table to `Plugs Same Store Sales - 454 Calendar`. +Let’s say we want to see same-store sales for Thanksgiving. The `Fiscal Day of the Year` value according to the 4-5-4 Calendar is `299` in week `43`. + +We can add a list page control to the page: -Notice that #4 shows no data for the Fiscal Year= 2019. Filter that out: + - +Configure it to filter based on the `Fiscal Week`: -Let's say we want to see the Sale Store Sales for Thanksgiving. Since 2022 is the most recent year we had a Thanksgiving, the `Fiscal Day of the Year` value according to the 4-5-4 Calendar is `299*`. + -[*The NRF Retail Calendars are located here.](https://nrf.com/resources/4-5-4-calendar) +And set its target to `Fiscal Week`: -Now we can see the year-over-year side by side with just a few clicks to expand as show: + + + + +Use the control to find week 43: -Of course we could make this more user-friendly by adding a Page Control to allow filtering that shows major holidays and other improvements but that is outside the scope of this QuickStart. +Click `Publish`. + +Of course, we could make this more user-friendly by making a control that shows major holidays by name and other improvements but that is outside the scope of this QuickStart. -[Link to the NRF Calendar Page](https://nrf.com/resources/4-5-4-calendar) +[NRF Calendar](https://nrf.com/resources/4-5-4-calendar) ![Footer](assets/sigma_footer.png) @@ -644,18 +739,18 @@ Of course we could make this more user-friendly by adding a Page Control to allo ## What we've covered Duration: 5 -In this QuickStart we covered many of the commonly used date functions and use cases where they are applied. This was not comprehensive and there are many more ways to leverage dates in Sigma. +In this QuickStart, we explored many of the most commonly used date functions and the use cases where they’re applied. While not comprehensive, this guide highlights key patterns and techniques for working with dates in Sigma. There are many more ways to leverage dates—so keep exploring! -[To get more information on date functions in Sigma, click here.](https://help.sigmacomputing.com/docs/popular-functions) +For more information, see [Function index](https://help.sigmacomputing.com/docs/function-index) - -**Additional Resource Links** +**Additional Resources:** Be sure to check out all the latest developments at [Sigma's First Friday Feature page!](https://quickstarts.sigmacomputing.com/firstfridayfeatures/) -[Help Center Home](https://help.sigmacomputing.com)
-[Sigma Community](https://community.sigmacomputing.com/)
-[Sigma Blog](https://www.sigmacomputing.com/blog/)
+[Blog](https://www.sigmacomputing.com/blog/)
+[Community](https://community.sigmacomputing.com/)
+[Help Center](https://help.sigmacomputing.com/hc/en-us)
+[QuickStarts](https://quickstarts.sigmacomputing.com/)

[](https://twitter.com/sigmacomputing)