diff --git a/docs-website/sidebars.js b/docs-website/sidebars.js index 03ea38fd622d4d..06396d60882778 100644 --- a/docs-website/sidebars.js +++ b/docs-website/sidebars.js @@ -437,7 +437,7 @@ module.exports = { Observability: [ "docs/managed-datahub/observe/freshness-assertions", "docs/managed-datahub/observe/volume-assertions", - "docs/managed-datahub/observe/custom-assertions", + "docs/managed-datahub/observe/custom-sql-assertions", ], }, ], diff --git a/docs/managed-datahub/observe/custom-assertions.md b/docs/managed-datahub/observe/custom-sql-assertions.md similarity index 77% rename from docs/managed-datahub/observe/custom-assertions.md rename to docs/managed-datahub/observe/custom-sql-assertions.md index e221cf1058fd08..d4a09b434ca799 100644 --- a/docs/managed-datahub/observe/custom-assertions.md +++ b/docs/managed-datahub/observe/custom-sql-assertions.md @@ -4,12 +4,12 @@ description: This page provides an overview of working with DataHub SQL Assertio import FeatureAvailability from '@site/src/components/FeatureAvailability'; -# Custom Assertions +# Custom SQL Assertions -> ⚠️ The **Custom Assertions** feature is currently in private beta, part of the **Acryl Observe** module, and may only be available to a +> ⚠️ The **Custom SQL Assertions** feature is currently in private beta, part of the **Acryl Observe** module, and may only be available to a > limited set of design partners. > > If you are interested in trying it and providing feedback, please reach out to your Acryl Customer Success @@ -27,18 +27,18 @@ changes to key metric definitions, etc. Often times, these changes break importa like reporting dashboards or data-driven product features. What if you could reduce the time to detect these incidents, so that the people responsible for the data were made aware of data -issues _before_ anyone else? With Acryl DataHub **Custom Assertions**, you can. +issues _before_ anyone else? With Acryl DataHub **Custom SQL Assertions**, you can. Acryl DataHub allows users to define complex expectations about a particular warehouse Table through custom SQL queries, and then monitor those expectations over time as the table grows and changes. -In this article, we'll cover the basics of monitoring Custom Assertions - what they are, how to configure them, and more - so that you and your team can +In this article, we'll cover the basics of monitoring Custom SQL Assertions - what they are, how to configure them, and more - so that you and your team can start building trust in your most important data assets. Let's get started! ## Support -Custom Assertions are currently supported for: +Custom SQL Assertions are currently supported for: 1. Snowflake 2. Redshift @@ -50,24 +50,24 @@ tab. > Note that SQL Assertions are not yet supported if you are connecting to your warehouse > using the DataHub CLI or a Remote Ingestion Executor. -## What is a Custom Assertion? +## What is a Custom SQL Assertion? -A **Custom Assertion** is a highly configurable Data Quality rule used to monitor a Data Warehouse Table -for unexpected or sudden changes in its meaning. Custom Assertions are defined through a raw SQL query that is evaluated against +A **Custom SQL Assertion** is a highly configurable Data Quality rule used to monitor a Data Warehouse Table +for unexpected or sudden changes in its meaning. Custom SQL Assertions are defined through a raw SQL query that is evaluated against the Table. You have full control over the SQL query, and can use any SQL features supported by your Data Warehouse. -Custom Assertions can be particularly useful when you have complex tables or relationships +Custom SQL Assertions can be particularly useful when you have complex tables or relationships that are used to generate important metrics or reports, and where the meaning of the table is expected to be stable over time. -If you have existing SQL queries that you already use to monitor your data, you may find that Custom Assertions are an easy way to port them +If you have existing SQL queries that you already use to monitor your data, you may find that Custom SQL Assertions are an easy way to port them to Acryl DataHub to get started. For example, imagine that you have a Table that tracks the number of purchases made on your company's e-commerce web store. You have a SQL query that you use to calculate the number of purchases made in the past 24 hours, and you'd like to monitor this -metric over time to ensure that it is always greater than 1000. You can use a Custom Assertion to do this! +metric over time to ensure that it is always greater than 1000. You can use a Custom SQL Assertion to do this! -### Anatomy of a Custom Assertion +### Anatomy of a Custom SQL Assertion -At the most basic level, **Custom Assertions** consist of a few important parts: +At the most basic level, **Custom SQL Assertions** consist of a few important parts: 1. An **Evaluation Schedule** 2. A **Query** @@ -86,8 +86,8 @@ minutes in an hour. #### 2. Query -The **Query**: This is the SQL query that will be used to evaluate the Table. The query should return a single row with a single column. Currently only numeric values are supported (integer and floats). The query can be as simple or as complex as you'd like, and can use any SQL features supported by your Data Warehouse. This requires that the configured user account has read access to the asset. Make sure to use the fully qualified name of the Table in your query. - +The **Query**: This is the SQL query that will be used to evaluate the Table. The query should return a **single row** containing a **single numeric column** (integers, floats). +The query can be as simple or as complex as you'd like, and can use any SQL features supported by your Data Warehouse. This requires that the configured user account has read access to the asset. Make sure to use the fully qualified name of the Table in your query. Use the "Try it out" button to test your query and ensure that it returns a single row with a single column. The query will be run against the Table in the context of the configured user account, so ensure that the user has read access to the Table. @@ -99,29 +99,29 @@ The **Condition Type**: This defines the conditions under which the Assertion wi - **Is Not Equal To**: The assertion will fail if the query result is not equal to the configured value - **Is Greater Than**: The assertion will fail if the query result is greater than the configured value - **Is Less Than**: The assertion will fail if the query result is less than the configured value -- **Is outside a range**: The assertion will fail if the query result is outside the configured range +- **Is Outside a Range**: The assertion will fail if the query result is outside the configured range - **Grows More Than**: The assertion will fail if the query result grows more than the configured range. This can be either a percentage (**Percentage**) or a number (**Value**). - **Grows Less Than**: The assertion will fail if the query result grows less than the configured percentage. This can be either a percentage (**Percentage**) or a number (**Value**). - **Growth is outside a range**: The assertion will fail if the query result growth is outside the configured range. This can be either a percentage (**Percentage**) or a number (**Value**). -Custom Assertions also have an off switch: they can be started or stopped at any time with the click of button. +Custom SQL Assertions also have an off switch: they can be started or stopped at any time with the click of button. #### 4. Assertion Description The **Assertion Description**: This is a human-readable description of the Assertion. It should be used to describe the meaning of the Assertion, and can be used to provide additional context to users who are viewing the Assertion. -## Creating a Custom Assertion +## Creating a Custom SQL Assertion ### Prerequisites -1. **Permissions**: To create or delete Custom Assertions for a specific entity on DataHub, you'll need to be granted the +1. **Permissions**: To create or delete Custom SQL Assertions for a specific entity on DataHub, you'll need to be granted the `Edit Assertions` and `Edit Monitors` privileges for the entity. This is granted to Entity owners by default. -2. **Data Platform Connection**: In order to create a Custom Assertion, you'll need to have an **Ingestion Source** configured to your +2. **Data Platform Connection**: In order to create a Custom SQL Assertion, you'll need to have an **Ingestion Source** configured to your Data Platform: Snowflake, BigQuery, or Redshift under the **Integrations** tab. -Once these are in place, you're ready to create your Custom Assertions! +Once these are in place, you're ready to create your Custom SQL Assertions! ### Steps @@ -168,23 +168,23 @@ Once these are in place, you're ready to create your Custom Assertions!

10. Click **Next** -11. Configure actions that should be taken when the Custom Assertion passes or fails +11. Configure actions that should be taken when the Custom SQL Assertion passes or fails

-- **Raise incident**: Automatically raise a new DataHub Incident for the Table whenever the Custom Assertion is failing. This +- **Raise incident**: Automatically raise a new DataHub Incident for the Table whenever the Custom SQL Assertion is failing. This may indicate that the Table is unfit for consumption. Configure Slack Notifications under **Settings** to be notified when an incident is created due to an Assertion failure. -- **Resolve incident**: Automatically resolved any incidents that were raised due to failures in this Custom Assertion. Note that +- **Resolve incident**: Automatically resolved any incidents that were raised due to failures in this Custom SQL Assertion. Note that any other incidents will not be impacted. 1. Click **Save**. -And that's it! DataHub will now begin to monitor your Custom Assertion for the table. +And that's it! DataHub will now begin to monitor your Custom SQL Assertion for the table. -To view the time of the next Custom Assertion evaluation, simply click **Custom** and then click on your +To view the time of the next Custom SQL Assertion evaluation, simply click **Custom** and then click on your new Assertion:

@@ -198,12 +198,12 @@ Once your assertion has run, you will begin to see Success or Failure status for

-## Stopping a Custom Assertion +## Stopping a Custom SQL Assertion -In order to temporarily stop the evaluation of a Custom Assertion: +In order to temporarily stop the evaluation of a Custom SQL Assertion: 1. Navigate to the **Validations** tab of the Table with the assertion -2. Click **Custom** to open the Custom Assertions list +2. Click **Custom** to open the Custom SQL Assertions list 3. Click the three-dot menu on the right side of the assertion you want to disable 4. Click **Stop** @@ -211,16 +211,16 @@ In order to temporarily stop the evaluation of a Custom Assertion:

-To resume the Custom Assertion, simply click **Turn On**. +To resume the Custom SQL Assertion, simply click **Turn On**.

-## Creating Custom Assertions via API +## Creating Custom SQL Assertions via API -Under the hood, Acryl DataHub implements Custom Assertion Monitoring using two "entity" concepts: +Under the hood, Acryl DataHub implements Custom SQL Assertion Monitoring using two "entity" concepts: - **Assertion**: The specific expectation for the custom assertion, e.g. "The table was changed in the past 7 hours" or "The table is changed on a schedule of every day by 8am". This is the "what". @@ -233,15 +233,15 @@ Note that to create or delete Assertions and Monitors for a specific entity on D #### GraphQL -In order to create a Custom Assertion that is being monitored on a specific **Evaluation Schedule**, you'll need to use 2 -GraphQL mutation queries to create a Custom Assertion entity and create an Assertion Monitor entity responsible for evaluating it. +In order to create a Custom SQL Assertion that is being monitored on a specific **Evaluation Schedule**, you'll need to use 2 +GraphQL mutation queries to create a Custom SQL Assertion entity and create an Assertion Monitor entity responsible for evaluating it. -Start by creating the Custom Assertion entity using the `createSqlAssertion` query and hang on to the 'urn' field of the Assertion entity +Start by creating the Custom SQL Assertion entity using the `createSqlAssertion` query and hang on to the 'urn' field of the Assertion entity you get back. Then continue by creating a Monitor entity using the `createAssertionMonitor`. ##### Examples -To create a Custom Assertion Entity that checks whether a query result is greater than 100: +To create a Custom SQL Assertion Entity that checks whether a query result is greater than 100: ```json mutation createSqlAssertion { @@ -265,7 +265,7 @@ mutation createSqlAssertion { } ``` -The supported custom assertion types are `METRIC` and `METRIC_CHANGE`. If you choose `METRIC_CHANGE`, +The supported assertion types are `METRIC` and `METRIC_CHANGE`. If you choose `METRIC_CHANGE`, you will need to provide a `changeType` parameter with either `ABSOLUTE` or `PERCENTAGE` values. The supported operator types are `EQUAL_TO`, `NOT_EQUAL_TO`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN`, `LESS_THAN_OR_EQUAL_TO`, and `BETWEEN` (requires minValue, maxValue). The supported parameter types are `NUMBER`.