> For the complete documentation index, see [llms.txt](https://docs.soda.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.soda.io/guides-and-tutorials/data-consumer/build-a-grafana-dashboard.md).

# Build a Grafana dashboard

Verify data contracts through the Soda Cloud API, store the check results in PostgreSQL, and chart them in a Grafana dashboard.

This guide shows how to build a data quality dashboard in Grafana from Soda check results. A Python script verifies the data contracts of a data source through the Soda Cloud API, waits for the scans to finish, and writes one row per check result to a PostgreSQL table. Grafana reads the table, which keeps the results of every run.

Use the example as a starting point and adapt the queries and panels to your own dashboard.

## Example dashboard

A data engineer wants one dashboard for the AdventureWorks datasets in a PostgreSQL data source. Two of them, `dim_product` and `fact_internet_sales`, have a published contract in Soda Cloud.

A Python script, `soda_results.py`, collects the results. Each time it runs, it:

1. Lists the datasets in the data source that have a contract
2. Verifies each contract, which starts a scan on the data source's Soda Runner
3. Polls each scan until it reaches a final state
4. Reads the checks of each scan and stores one row per check result in PostgreSQL

Grafana loads the PostgreSQL data source and the dashboard from provisioning files. The project has this layout:

```
soda-grafana/
├── soda_results.py
└── grafana/
    └── provisioning/
        ├── datasources/
        │   └── soda-results.yml
        └── dashboards/
            ├── soda.yml
            └── soda-check-results.json
```

## Prerequisites

* A data source in Soda Cloud that is connected to a Soda Runner, with a published contract on each dataset you want on the dashboard. See [Onboard datasets on Soda Cloud](https://docs.soda.io/soda-documentation/connect/onboard-data-sources-and-datasets/onboard-datasets-on-soda-cloud.md).
* A Soda Cloud API key. The user who generates the key needs the **Manage contracts** permission on the datasets, to verify their contracts. See [Generate API keys](https://docs.soda.io/apis/generate-api-keys.md) and [Global and dataset roles](https://docs.soda.io/soda-documentation/govern/organization-and-admin-settings/global-and-dataset-roles.md).
* A PostgreSQL database for the results, and a user that can create a table in it
* Python 3
* Grafana, with access to its provisioning folder, or Docker to run Grafana locally

## Install the libraries

Create a virtual environment in the project folder and install `requests`, to call the Soda Cloud API, and `psycopg`, to write to PostgreSQL:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install requests "psycopg[binary]"
```

## Create the script

The script reads its settings from environment variables:

| Variable                    | Value                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------ |
| `SODA_CLOUD_URL`            | `https://cloud.soda.io` or `https://cloud.us.soda.io`, depending on your Soda region |
| `SODA_CLOUD_API_KEY_ID`     | The ID of your Soda Cloud API key                                                    |
| `SODA_CLOUD_API_KEY_SECRET` | The secret of your Soda Cloud API key                                                |
| `SODA_DATA_SOURCE`          | The name of the data source in Soda Cloud                                            |
| `RESULTS_DB_HOST`           | Host name of the results database                                                    |
| `RESULTS_DB_PORT`           | Port of the results database. The default is `5432`.                                 |
| `RESULTS_DB_NAME`           | Name of the results database                                                         |
| `RESULTS_DB_USER`           | User that creates the results table and writes to it                                 |
| `RESULTS_DB_PASSWORD`       | Password of that user                                                                |

Save the script in the project folder:

{% code title="soda\_results.py" %}

```python
import os
import sys
import time

import psycopg
import requests

SODA_API = os.environ["SODA_CLOUD_URL"].rstrip("/") + "/api/v1"
AUTH = (os.environ["SODA_CLOUD_API_KEY_ID"], os.environ["SODA_CLOUD_API_KEY_SECRET"])
DATA_SOURCE = os.environ["SODA_DATA_SOURCE"]

FINAL_STATES = {
    "completed", "completedWithWarnings", "completedWithFailures",
    "completedWithErrors", "failed", "canceled", "timedOut",
}
NO_RESULTS_STATES = {"failed", "canceled", "timedOut"}
POLL_SECONDS = 10
TIMEOUT_SECONDS = 30 * 60

CREATE_TABLE = """
CREATE TABLE IF NOT EXISTS soda_check_results (
    scan_id     text        NOT NULL,
    scan_time   timestamptz NOT NULL,
    scan_state  text        NOT NULL,
    data_source text        NOT NULL,
    dataset     text        NOT NULL,
    check_id    text        NOT NULL,
    check_name  text        NOT NULL,
    column_name text,
    check_type  text,
    outcome     text        NOT NULL,
    check_url   text,
    PRIMARY KEY (scan_id, check_id)
)
"""

CREATE_VIEW = """
CREATE OR REPLACE VIEW soda_latest_check_results AS
SELECT r.*
FROM soda_check_results r
JOIN (
    SELECT DISTINCT ON (data_source, dataset) data_source, dataset, scan_id
    FROM soda_check_results
    ORDER BY data_source, dataset, scan_time DESC
) latest USING (data_source, dataset, scan_id)
"""

INSERT_ROW = """
INSERT INTO soda_check_results (
    scan_id, scan_time, scan_state, data_source, dataset,
    check_id, check_name, column_name, check_type, outcome, check_url
) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
ON CONFLICT (scan_id, check_id) DO NOTHING
"""


def get(path, **params):
    response = requests.get(f"{SODA_API}/{path}", auth=AUTH, params=params, timeout=30)
    response.raise_for_status()
    return response.json()


def get_all(path, **params):
    page = 0
    while True:
        body = get(path, size=100, page=page, **params)
        yield from body["content"]
        if body["last"]:
            return
        page += 1


def verify(contract_id):
    while True:
        response = requests.post(
            f"{SODA_API}/contracts/{contract_id}/verify", auth=AUTH, json={}, timeout=30
        )
        if response.status_code == 429:  # rate limit: 10 verifications per 60 seconds
            time.sleep(60)
            continue
        response.raise_for_status()
        return response.headers["X-Soda-Scan-Id"]


def wait_for(scan_id):
    deadline = time.monotonic() + TIMEOUT_SECONDS
    while True:
        scan = get(f"scans/{scan_id}")
        if scan["state"] in FINAL_STATES:
            return scan
        if time.monotonic() > deadline:
            raise TimeoutError(f"Scan {scan_id} is still {scan['state']}")
        time.sleep(POLL_SECONDS)


def result_rows(scan, dataset):
    outcomes = {check["id"]: check["evaluationStatus"] for check in scan.get("checks") or []}
    check_ids = list(outcomes)
    scan_time = scan.get("scanTime") or scan["created"]
    for start in range(0, len(check_ids), 1000):  # checkIds takes up to 1000 IDs
        batch = ",".join(check_ids[start:start + 1000])
        for check in get("checks", checkIds=batch)["content"]:
            yield (
                scan["id"], scan_time, scan["state"], DATA_SOURCE, dataset,
                check["id"], check["name"], check.get("column"), check.get("checkType"),
                outcomes[check["id"]], check.get("cloudUrl"),
            )


def main():
    datasets = list(get_all("datasets", datasourceName=DATA_SOURCE, hasContract="true"))
    if not datasets:
        sys.exit(f"No dataset with a contract in data source {DATA_SOURCE}")

    scans = []
    for dataset in datasets:
        scan_id = verify(dataset["contractId"])
        print(f"{dataset['name']}: verification started, scan {scan_id}")
        scans.append((dataset["name"], scan_id))

    no_results = []
    with psycopg.connect(
        host=os.environ["RESULTS_DB_HOST"],
        port=os.environ.get("RESULTS_DB_PORT", "5432"),
        dbname=os.environ["RESULTS_DB_NAME"],
        user=os.environ["RESULTS_DB_USER"],
        password=os.environ["RESULTS_DB_PASSWORD"],
    ) as conn:
        conn.execute(CREATE_TABLE)
        conn.execute(CREATE_VIEW)
        for dataset, scan_id in scans:
            scan = wait_for(scan_id)
            if scan["state"] in NO_RESULTS_STATES:
                print(f"{dataset}: scan {scan['state']}: {scan.get('failureReason') or ''}")
                no_results.append(dataset)
                continue
            rows = list(result_rows(scan, dataset))
            with conn.cursor() as cur:
                cur.executemany(INSERT_ROW, rows)
            conn.commit()
            print(f"{dataset}: scan {scan['state']}, {len(rows)} check results stored")

    if no_results:
        sys.exit(f"No check results for: {', '.join(no_results)}")


if __name__ == "__main__":
    main()
```

{% endcode %}

A few details in the script:

* `POST /api/v1/contracts/{contractId}/verify` starts a verification and returns the scan ID in the `X-Soda-Scan-Id` header. The endpoint accepts 10 requests per 60 seconds, so when it responds with `429`, the script waits a minute and tries again.
* A scan goes through `queuing`, `executing`, and `started` before it reaches a final state. The script polls `GET /api/v1/scans/{scanId}` every 10 seconds and stops on any final state: `completed`, `completedWithWarnings`, `completedWithFailures`, `completedWithErrors`, `failed`, `canceled`, or `timedOut`.
* For a scan that ends in `failed`, `canceled`, or `timedOut`, the script stores no results. It prints the scan's `failureReason`, stores the results of the other scans, and then exits with an error.
* The outcome of each check comes from the `checks` list of the scan. The check's name, column, and type come from `GET /api/v1/checks`, which takes up to 1000 check IDs in its `checkIds` parameter.
* The insert passes every value as a query parameter. `ON CONFLICT DO NOTHING` skips the rows of a scan that is already stored.
* The view `soda_latest_check_results` holds the results of the latest stored scan of each dataset.

> For every endpoint and response field, see the [REST API reference](https://docs.soda.io/apis/rest-api.md).

{% hint style="info" %}
Coming from Soda v3? The v3 version of this guide started a scan definition with `POST /api/v1/scans`. In v4, you verify the contract of each dataset with `POST /api/v1/contracts/{contractId}/verify`, and `GET /api/v1/scans/{scanId}` reports the state and check results of the scan as before.
{% endhint %}

## Run the script

Set the environment variables and run the script:

```bash
export SODA_CLOUD_URL=https://cloud.us.soda.io
export SODA_CLOUD_API_KEY_ID=<your_api_key_id>
export SODA_CLOUD_API_KEY_SECRET=<your_api_key_secret>
export SODA_DATA_SOURCE=<your_data_source_name>
export RESULTS_DB_HOST=<results_db_host>
export RESULTS_DB_NAME=<results_db_name>
export RESULTS_DB_USER=<results_db_user>
export RESULTS_DB_PASSWORD=<results_db_password>
python soda_results.py
```

The script prints a line for each contract it verifies and each scan it stores:

```
dim_product: verification started, scan 96647ba3-83ac-4ef3-95f3-5e6ea2196575
fact_internet_sales: verification started, scan 97a4978f-5bbe-481a-b41a-5f8277a04680
dim_product: scan completedWithWarnings, 6 check results stored
fact_internet_sales: scan completedWithFailures, 5 check results stored
```

In this run, `fact_internet_sales` has a sale with an amount of `0`, so its contract fails. `dim_product` has a product without a subcategory, so its contract warns.

Run the script on a schedule, for example from cron or your orchestrator, to collect the results over time.

## Provision Grafana

Grafana reads data sources and dashboards from YAML files in its provisioning folder when it starts. See [Provision Grafana](https://grafana.com/docs/grafana/latest/administration/provisioning/) in the Grafana documentation.

### Create a read-only user

Grafana doesn't validate the safety of the SQL queries that panels run, so give it a database user that can only read the results. After the script's first run has created the table and the view, run these statements as a database administrator:

```sql
CREATE USER grafanareader WITH PASSWORD '<grafana_password>';
GRANT USAGE ON SCHEMA public TO grafanareader;
GRANT SELECT ON soda_check_results, soda_latest_check_results TO grafanareader;
```

### Add the data source

Grafana replaces each `$__env{…}` with the value of an environment variable, so the file holds no credentials:

{% code title="grafana/provisioning/datasources/soda-results.yml" %}

```yaml
apiVersion: 1

datasources:
  - name: Soda results
    uid: soda-results
    type: grafana-postgresql-datasource
    url: $__env{RESULTS_DB_HOST}:$__env{RESULTS_DB_PORT}
    user: $__env{GRAFANA_DB_USER}
    secureJsonData:
      password: $__env{GRAFANA_DB_PASSWORD}
    jsonData:
      database: $__env{RESULTS_DB_NAME}
      sslmode: $__env{RESULTS_DB_SSLMODE}
```

{% endcode %}

Besides the results database settings of the script, the file reads `GRAFANA_DB_USER` and `GRAFANA_DB_PASSWORD`, the read-only user, and `RESULTS_DB_SSLMODE`, the TLS/SSL mode: `disable`, `require`, `verify-ca`, or `verify-full`. Most cloud-hosted PostgreSQL services require at least `require`. See [Configure the PostgreSQL data source](https://grafana.com/docs/grafana/latest/datasources/postgres/configure/) in the Grafana documentation.

### Add the dashboard

The dashboard provider tells Grafana to load the dashboard files from `/etc/grafana/provisioning/dashboards`, the default provisioning folder of the Grafana Docker image. If your Grafana reads provisioning files from another folder, change `path`:

{% code title="grafana/provisioning/dashboards/soda.yml" %}

```yaml
apiVersion: 1

providers:
  - name: Soda
    type: file
    options:
      path: /etc/grafana/provisioning/dashboards
```

{% endcode %}

The dashboard has four panels, each with a SQL query on the results table or view:

| Panel                                 | What it shows                                                                                             |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Latest results**                    | The number of passed, warned, failed, and not evaluated checks in the latest scan of each dataset         |
| **Latest results by dataset**         | The same results, per dataset                                                                             |
| **Failed and warned checks per scan** | The number of failed and warned checks in every stored scan, per dataset, over the dashboard's time range |
| **Latest check results**              | One row per check, failed and warned checks first                                                         |

{% code title="grafana/provisioning/dashboards/soda-check-results.json" %}

```json
{
  "uid": "soda-check-results",
  "title": "Soda check results",
  "tags": [
    "soda"
  ],
  "time": {
    "from": "now-7d",
    "to": "now"
  },
  "refresh": "5m",
  "schemaVersion": 41,
  "panels": [
    {
      "id": 1,
      "type": "stat",
      "title": "Latest results",
      "datasource": {
        "type": "grafana-postgresql-datasource",
        "uid": "soda-results"
      },
      "gridPos": {
        "x": 0,
        "y": 0,
        "w": 24,
        "h": 3
      },
      "targets": [
        {
          "refId": "A",
          "datasource": {
            "type": "grafana-postgresql-datasource",
            "uid": "soda-results"
          },
          "editorMode": "code",
          "format": "table",
          "rawQuery": true,
          "rawSql": "SELECT count(*) FILTER (WHERE outcome = 'pass') AS \"Passed\", count(*) FILTER (WHERE outcome = 'warn') AS \"Warned\", count(*) FILTER (WHERE outcome = 'fail') AS \"Failed\", count(*) FILTER (WHERE outcome = 'notEvaluated') AS \"Not evaluated\"\nFROM soda_latest_check_results"
        }
      ],
      "options": {
        "reduceOptions": {
          "calcs": [
            "lastNotNull"
          ],
          "fields": "",
          "values": false
        },
        "colorMode": "background",
        "graphMode": "none",
        "textMode": "value_and_name",
        "orientation": "vertical"
      },
      "fieldConfig": {
        "defaults": {
          "unit": "none"
        },
        "overrides": [
          {
            "matcher": {
              "id": "byName",
              "options": "Passed"
            },
            "properties": [
              {
                "id": "color",
                "value": {
                  "mode": "fixed",
                  "fixedColor": "green"
                }
              }
            ]
          },
          {
            "matcher": {
              "id": "byName",
              "options": "Warned"
            },
            "properties": [
              {
                "id": "color",
                "value": {
                  "mode": "fixed",
                  "fixedColor": "orange"
                }
              }
            ]
          },
          {
            "matcher": {
              "id": "byName",
              "options": "Failed"
            },
            "properties": [
              {
                "id": "color",
                "value": {
                  "mode": "fixed",
                  "fixedColor": "red"
                }
              }
            ]
          },
          {
            "matcher": {
              "id": "byName",
              "options": "Not evaluated"
            },
            "properties": [
              {
                "id": "color",
                "value": {
                  "mode": "fixed",
                  "fixedColor": "text"
                }
              }
            ]
          }
        ]
      }
    },
    {
      "id": 2,
      "type": "barchart",
      "title": "Latest results by dataset",
      "datasource": {
        "type": "grafana-postgresql-datasource",
        "uid": "soda-results"
      },
      "gridPos": {
        "x": 0,
        "y": 3,
        "w": 10,
        "h": 6
      },
      "targets": [
        {
          "refId": "A",
          "datasource": {
            "type": "grafana-postgresql-datasource",
            "uid": "soda-results"
          },
          "editorMode": "code",
          "format": "table",
          "rawQuery": true,
          "rawSql": "SELECT dataset, count(*) FILTER (WHERE outcome = 'pass') AS \"Passed\", count(*) FILTER (WHERE outcome = 'warn') AS \"Warned\", count(*) FILTER (WHERE outcome = 'fail') AS \"Failed\"\nFROM soda_latest_check_results\nGROUP BY dataset\nORDER BY dataset"
        }
      ],
      "options": {
        "orientation": "horizontal",
        "stacking": "normal",
        "xField": "dataset"
      },
      "fieldConfig": {
        "defaults": {
          "custom": {
            "fillOpacity": 80
          }
        },
        "overrides": [
          {
            "matcher": {
              "id": "byName",
              "options": "Passed"
            },
            "properties": [
              {
                "id": "color",
                "value": {
                  "mode": "fixed",
                  "fixedColor": "green"
                }
              }
            ]
          },
          {
            "matcher": {
              "id": "byName",
              "options": "Warned"
            },
            "properties": [
              {
                "id": "color",
                "value": {
                  "mode": "fixed",
                  "fixedColor": "orange"
                }
              }
            ]
          },
          {
            "matcher": {
              "id": "byName",
              "options": "Failed"
            },
            "properties": [
              {
                "id": "color",
                "value": {
                  "mode": "fixed",
                  "fixedColor": "red"
                }
              }
            ]
          }
        ]
      }
    },
    {
      "id": 3,
      "type": "timeseries",
      "title": "Failed and warned checks per scan",
      "datasource": {
        "type": "grafana-postgresql-datasource",
        "uid": "soda-results"
      },
      "gridPos": {
        "x": 10,
        "y": 3,
        "w": 14,
        "h": 6
      },
      "targets": [
        {
          "refId": "A",
          "datasource": {
            "type": "grafana-postgresql-datasource",
            "uid": "soda-results"
          },
          "editorMode": "code",
          "format": "time_series",
          "rawQuery": true,
          "rawSql": "SELECT scan_time AS \"time\", dataset AS metric,\n       count(*) FILTER (WHERE outcome IN ('fail', 'warn')) AS value\nFROM soda_check_results\nWHERE $__timeFilter(scan_time)\nGROUP BY scan_time, dataset\nORDER BY scan_time"
        }
      ],
      "options": {
        "tooltip": {
          "mode": "multi"
        }
      },
      "fieldConfig": {
        "defaults": {
          "min": 0,
          "decimals": 0,
          "custom": {
            "drawStyle": "line",
            "lineWidth": 2,
            "pointSize": 8,
            "showPoints": "always"
          }
        }
      }
    },
    {
      "id": 4,
      "type": "table",
      "title": "Latest check results",
      "datasource": {
        "type": "grafana-postgresql-datasource",
        "uid": "soda-results"
      },
      "gridPos": {
        "x": 0,
        "y": 9,
        "w": 24,
        "h": 13
      },
      "targets": [
        {
          "refId": "A",
          "datasource": {
            "type": "grafana-postgresql-datasource",
            "uid": "soda-results"
          },
          "editorMode": "code",
          "format": "table",
          "rawQuery": true,
          "rawSql": "SELECT dataset AS \"Dataset\", check_name AS \"Check\", column_name AS \"Column\",\n       outcome AS \"Outcome\", scan_time AS \"Scan time\"\nFROM soda_latest_check_results\nORDER BY CASE outcome WHEN 'fail' THEN 0 WHEN 'warn' THEN 1 ELSE 2 END, dataset, check_name"
        }
      ],
      "options": {
        "showHeader": true
      },
      "fieldConfig": {
        "defaults": {},
        "overrides": [
          {
            "matcher": {
              "id": "byName",
              "options": "Outcome"
            },
            "properties": [
              {
                "id": "custom.cellOptions",
                "value": {
                  "type": "color-background"
                }
              },
              {
                "id": "mappings",
                "value": [
                  {
                    "type": "value",
                    "options": {
                      "pass": {
                        "text": "Passed",
                        "color": "green",
                        "index": 0
                      },
                      "warn": {
                        "text": "Warned",
                        "color": "orange",
                        "index": 1
                      },
                      "fail": {
                        "text": "Failed",
                        "color": "red",
                        "index": 2
                      },
                      "notEvaluated": {
                        "text": "Not evaluated",
                        "color": "text",
                        "index": 3
                      }
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    }
  ]
}
```

{% endcode %}

> To change the panels, see [Visualizations](https://grafana.com/docs/grafana/latest/visualizations/panels-visualizations/visualizations/) and the [PostgreSQL query editor](https://grafana.com/docs/grafana/latest/datasources/postgres/query-editor/) in the Grafana documentation.

## Start Grafana

To try the dashboard on your machine, run Grafana in Docker with the `provisioning` folder mounted at `/etc/grafana/provisioning`. Set `RESULTS_DB_HOST` to an address of the results database that the container can reach.

```bash
export GRAFANA_DB_USER=grafanareader
export GRAFANA_DB_PASSWORD=<grafana_password>
export RESULTS_DB_PORT=5432
export RESULTS_DB_SSLMODE=require
docker run -d --name grafana -p 3000:3000 \
  -e RESULTS_DB_HOST -e RESULTS_DB_PORT -e RESULTS_DB_NAME -e RESULTS_DB_SSLMODE \
  -e GRAFANA_DB_USER -e GRAFANA_DB_PASSWORD \
  -v "$PWD/grafana/provisioning:/etc/grafana/provisioning" \
  grafana/grafana:13.2.4
```

Open `http://localhost:3000` and sign in with `admin` as the user name and password. See [Sign in to Grafana](https://grafana.com/docs/grafana/latest/setup-grafana/sign-in-to-grafana/) in the Grafana documentation. Then open **Dashboards** > **Soda check results**.

<figure><img src="https://1928210810-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJJOow5YZtrrxZJBNXV2D%2Fuploads%2Fgit-blob-fa6e445ef7d9335cffe984d601eabafb5f4c4f13%2Fbuild-a-grafana-dashboard-grafana-dashboard.png?alt=media" alt="The Soda check results dashboard in Grafana, with one failed check on fact_internet_sales and one warned check on dim_product"><figcaption><p>The dashboard after two runs of the script: the second run found a sale with an amount of 0</p></figcaption></figure>

## Next steps

* Get notified in Soda Cloud when a check fails, with [Notifications](https://docs.soda.io/soda-documentation/fix/notifications.md).
* Investigate the rows that fail a check with [Diagnostics Warehouse](https://docs.soda.io/soda-documentation/understand/diagnostics-warehouse.md).
* Alert on the results table from Grafana with [Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.soda.io/guides-and-tutorials/data-consumer/build-a-grafana-dashboard.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
