diff --git a/docs/docusaurus/docs/core/customize_expectations/_examples/use_sql_to_define_a_custom_expectation.py b/docs/docusaurus/docs/core/customize_expectations/_examples/use_sql_to_define_a_custom_expectation.py index a6dad57282c9..f6dca8a12570 100644 --- a/docs/docusaurus/docs/core/customize_expectations/_examples/use_sql_to_define_a_custom_expectation.py +++ b/docs/docusaurus/docs/core/customize_expectations/_examples/use_sql_to_define_a_custom_expectation.py @@ -35,32 +35,36 @@ def set_up_context_for_example(context): # import great_expectations as gx +# Define your custom SQL query. +# +my_query = """ + SELECT + * + FROM + {batch} + WHERE + passenger_count > 6 or passenger_count < 0 + """ +# -# Define a custom Expectation that uses SQL by subclassing UnexpectedRowsExpectation -# -# -# -class ExpectPassengerCountToBeLegal(gx.expectations.UnexpectedRowsExpectation): - # - unexpected_rows_query: str = ( - "SELECT * FROM {batch} WHERE passenger_count > 6 or passenger_count < 0" - ) - # - description: str = "There should be no more than **6** passengers." - +# Customize how the Expectation renders in Data Docs. +# +my_description = "There should be no more than **6** passengers." +# +# Create an Expectation using the UnexpectedRowsExpectation class and your parameters. +# +expect_passenger_count_to_be_legal = gx.expectations.UnexpectedRowsExpectation( + unexpected_rows_query=my_query, + description=my_description, +) # +# Test the Expectation. context = gx.get_context() # Hide this set_up_context_for_example(context) -# Instantiate the custom Expectation -# -expectation = ExpectPassengerCountToBeLegal() -# - -# Test the Expectation data_source_name = "my_sql_data_source" data_asset_name = "my_data_asset" batch_definition_name = "my_batch_definition" @@ -71,5 +75,5 @@ class ExpectPassengerCountToBeLegal(gx.expectations.UnexpectedRowsExpectation): .get_batch() ) -batch.validate(expectation) +batch.validate(expect_passenger_count_to_be_legal) # diff --git a/docs/docusaurus/docs/core/customize_expectations/use_sql_to_define_a_custom_expectation.md b/docs/docusaurus/docs/core/customize_expectations/use_sql_to_define_a_custom_expectation.md index 91028741bb14..f693ad90e35d 100644 --- a/docs/docusaurus/docs/core/customize_expectations/use_sql_to_define_a_custom_expectation.md +++ b/docs/docusaurus/docs/core/customize_expectations/use_sql_to_define_a_custom_expectation.md @@ -9,9 +9,7 @@ import PrereqGxInstalled from '../_core_components/prerequisites/_gx_installatio import PrereqPreconfiguredDataContext from '../_core_components/prerequisites/_preconfigured_data_context.md'; import PrereqPreconfiguredDataSourceAndAsset from '../_core_components/prerequisites/_data_source_and_asset_connected_to_data.md'; -Among the available Expectations, the `UnexpectedRowsExpectation` is designed to facilitate the execution of SQL or Spark-SQL queries as the core logic for an Expectation. By default, `UnexpectedRowsExpectation` considers validation successful when no rows are returned by the provided SQL query. - -Like any other Expectation, you can instantiate the `UnexpectedRowsExpectation` directly. You can also customize an `UnexpectedRowsExpectation` in essentially the same manner as you would [define a custom Expectation](/core/customize_expectations/define_a_custom_expectation_class.md), by subclassing `UnexpectedRowsExpectation` and providing customized default attributes and text for Data Docs. However, there are some caveats around the `UnexpectedRowsExpectation`'s `unexpected_rows_query` attribute that deserve further detail. +Among the available Expectations, the `UnexpectedRowsExpectation` is designed to facilitate the execution of SQL queries as the core logic for an Expectation. By default, `UnexpectedRowsExpectation` considers validation successful when no rows are returned by the provided SQL query. @@ -37,38 +35,35 @@ Like any other Expectation, you can instantiate the `UnexpectedRowsExpectation` -1. Create a new Expectation class that inherits the `UnexpectedRowsExpectation` class. - - The class name `UnexpectedRowsExpectation` describes the functionality of the Expectation: it finds rows with unexpected values. When you create a customized Expectation class you can provide a class name that is more indicative of your specific use case. In this example, the customized subclass of `UnexpectedRowsExpectation` will be used to find invalid passenger counts in taxi trip data: - - ```python title="Python" name="docs/docusaurus/docs/core/customize_expectations/_examples/use_sql_to_define_a_custom_expectation.py - define a more descriptive name for an UnexpectedRowsExpectation" - ``` - -2. Override the Expectation's `unexpected_rows_query` attribute. +1. Determine your custom SQL query. - The `unexpected_rows_query` attribute is a SQL or Spark-SQL query that returns a selection of rows from the Batch of data being validated. By default, rows that are returned have failed the validation check. + The `UnexpectedRowsExpectation` class takes an `unexpected_rows_query` attribute, which is a SQL or Spark-SQL query that returns a selection of rows from the Batch of data being validated. By default, rows that are returned have failed the validation check. - The `unexpected_rows_query` should be written in standard SQL or Spark-SQL syntax, except that it can also contain the special `{batch}` named query. When the Expectation is evaluated, the `{batch}` keyword will be replaced with the Batch of data that is configured for your Data Asset. + The custom SQL query should be written in the SQL dialect your database uses, except that it can also contain the special `{batch}` named query. When the Expectation is evaluated, the `{batch}` keyword will be replaced with the Batch of data that is configured for your Data Asset. - In this example, `unexpected_rows_query` will select any rows where the passenger count is greater than `6` or less than `0`. These rows will fail validation for this Expectation: + In this example, the custom query will select any rows where the passenger count is greater than `6` or less than `0`: - ```python title="Python" name="docs/docusaurus/docs/core/customize_expectations/_examples/use_sql_to_define_a_custom_expectation.py - define the query for an UnexpectedRowsExpectation" + ```python title="Python" name="docs/docusaurus/docs/core/customize_expectations/_examples/use_sql_to_define_a_custom_expectation.py - define query" ``` -3. Customize the rendering of the new Expectation when displayed in Data Docs. +2. Customize how the Expectation renders in Data Docs. - As with other Expectations, the `description` attribute contains the text describing the customized Expectation when your results are rendered into Data Docs. It can be set when an Expectation class is defined or edited as an attribute of an Expectation instance. You can format the `description` string with Markdown syntax: + As with other Expectations, the `description` attribute contains the text describing the Expectation when your results are rendered into Data Docs. You can format the `description` string with Markdown syntax: - ```python title="Python" name="docs/docusaurus/docs/core/customize_expectations/_examples/use_sql_to_define_a_custom_expectation.py - define a custom UnexpectedRowsExpectation" + ```python title="Python" name="docs/docusaurus/docs/core/customize_expectations/_examples/use_sql_to_define_a_custom_expectation.py - define description" ``` -4. Use the customized subclass as an Expectation. - - Once the customized Expectation subclass has been defined, instances of it can be created, added to Expectation Suites, and validated just like any other Expectation class: +3. Create a new Expectation using the `UnexpectedRowsExpectation` class and your parameters. + + The class name `UnexpectedRowsExpectation` describes the functionality of the Expectation: it finds rows with unexpected values. When you create your Expectation, you can use a name that is more indicative of your specific use case. In this example, the customized Expectation will be used to find invalid passenger counts in taxi trip data: - ```python title="Python" name="docs/docusaurus/docs/core/customize_expectations/_examples/use_sql_to_define_a_custom_expectation.py - instantiate the custom SQL Expectation" + ```python title="Python" name="docs/docusaurus/docs/core/customize_expectations/_examples/use_sql_to_define_a_custom_expectation.py - create Expectation" ``` +4. Use your custom SQL Expectation. + + Now that you've created a custom SQL Expectation, you can [add it to an Expectation Suite](/core/define_expectations/organize_expectation_suites.md) and [validate it](/docs/core/run_validations/run_a_validation_definition.md) like any other Expectation. +