Skip to main content
Version: 0.18.17

Add comments to Expectations and display them in Data Docs

This guide will help you add descriptive comments (or notes, here used interchangeably) to ExpectationsA verifiable assertion about data. and display those comments in Data DocsHuman readable documentation generated from Great Expectations metadata detailing Expectations, Validation Results, etc.. In these comments you can add some clarification or motivation to the Expectation definition to help you communicate more clearly with your team about specific Expectations. Markdown is supported in these comments.

Prerequisites

Edit your Expectation Suite

Terminal input
great_expectations suite edit <your_suite_name>

Add comments to specific Expectations

For each Expectation you wish to add notes to, add a dictionary to the meta field with the key notes and your comment as the value. Here is an example.

Python
validator.expect_table_row_count_to_be_between(
max_value=1000000, min_value=1,
meta={"notes": "Example notes about this expectation."}
)

Leads to the following representation in the Data DocsHuman readable documentation generated from Great Expectations metadata detailing Expectations, Validation Results, etc. (For Expectation SuiteA collection of verifiable assertions about data. pages, click on the speech bubble to view the comment).

Expectation with simple comment, no formatting

Add styling to your comments (Optional)

To add styling to your comments, you can add formatted notes. Here are a few examples.

A single line of markdown is rendered in red, with any Markdown formatting applied.

Python
validator.expect_column_values_to_not_be_null(
column="column_name",
notes="Example notes about this expectation. **Markdown** `Supported`.",
)

Expectation with a single line of markdown comment is rendered in red with markdown formatting

Multiple lines can be rendered by using a list of notes; these lines are rendered in black text with any Markdown formatting applied.

Python
validator.expect_column_values_to_not_be_null(
column="column_name",
notes=[
"Example notes about this expectation. **Markdown** `Supported`.",
"Second example note **with** *Markdown*",
],
)

Multiple lines of markdown rendered with formatting

Review your comments in the Expectation Suite overview of your Data Docs

You can open your Data Docs by using the .open_data_docs() method of your Data Context, which should be present in the last cell of the Jupyter Notebook you did your editing in.