> For the complete documentation index, see [llms.txt](https://docs.dataplex-consulting.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dataplex-consulting.com/data-catalog/cms-data-feeds-dataset/cms-data-feeds-catalog/nursing-homes-including-rehab-services-state-us-averages.md). # Nursing Homes Including Rehab Services - State US Averages Part of the [CMS Data Feeds Dataset](/data-catalog/cms-data-feeds-dataset/cms-data-feeds-catalog.md) › Medicare Dataplex delivers this CMS feed as the analysis-ready table `DWV.NURSING_HOMES_STATE_US_AVERAGES` on Snowflake and Databricks — 82 snapshot releases spanning 2019–2026, aligned to a single schema, refreshed automatically whenever CMS publishes a new file. Every row carries lineage back to the exact CMS source file that produced it. ## Key facts | | | | ------------------ | ---------------------------------------------------- | | **Snowflake** | `DWV.NURSING_HOMES_STATE_US_AVERAGES` | | **Databricks** | `cms_dwv.nursing_homes_state_us_averages` | | **Cadence** | Monthly | | **Update pattern** | Full-refresh — each file replaces the prior snapshot | | **CMS published** | 2026-06-01 | | **Loaded** | 2026-06-29 | | **Columns** | 50 data + 6 lineage | | **File versions** | 82 | | **License** | CMS public data — U.S. Government work | | **Platforms** | Snowflake Marketplace · Databricks Delta Sharing | Included in the CMS Data Feeds Dataset — [start a free trial on Snowflake Marketplace](https://app.snowflake.com/marketplace/listing/GZT1Z125KDH/dataplex-consulting-data-products-cms-data-feeds-dataset). {% hint style="info" %} **Last CMS publication 2026-06-01** — awaiting the next release. New files load automatically when CMS publishes. {% endhint %} {% hint style="info" %} **Full-refresh feed** — each file version is a complete snapshot and newer files supersede older ones. Filter to the latest file (see the sample query) to avoid double-counting across versions. {% endhint %} ## Sample queries {% tabs %} {% tab title="Snowflake" %} ```sql -- Latest snapshot only (avoids double-counting across file versions) SELECT * FROM DWV.NURSING_HOMES_STATE_US_AVERAGES WHERE FILE_ID IN ( SELECT ID FROM DWV.FEEDS_FILES WHERE IS_LATEST = 1 ) LIMIT 100; ``` {% endtab %} {% tab title="Databricks" %} ```sql -- Latest snapshot only (avoids double-counting across file versions) SELECT * FROM cms_dwv.nursing_homes_state_us_averages WHERE file_id IN ( SELECT id FROM cms_dwv.feeds_files WHERE is_latest = 1 ) LIMIT 100; ``` {% endtab %} {% endtabs %} ## About this feed > Average ratings, staffing hours, quality measure percentages, and penalty counts by state/territory. One row per state plus US total. > > — *Source: CMS feed metadata* **Keywords:** nursing homes, state averages, quality measures **Theme:** Medicare ## Coverage timeline 2019–2026 🟩🟩🟩🟩🟩🟩🟩🟩 (🟩 covered · ⬜ no data) 8 of 8 years with snapshot releases — no gaps. ## Release history | Reporting period | CMS published | Loaded | Latest file | | ------------------------- | ------------- | ---------- | ----------- | | Snapshot as of 2026-06-01 | 2026-06-01 | 2026-06-29 | ✓ | | Snapshot as of 2026-05-01 | 2026-05-01 | 2026-05-28 | | | Snapshot as of 2026-04-01 | 2026-04-01 | 2026-04-29 | | | Snapshot as of 2026-03-01 | 2026-03-01 | 2026-03-26 | | | Snapshot as of 2026-02-01 | 2026-02-01 | 2026-03-25 | | | Snapshot as of 2020-07-01 | 2020-07-01 | 2026-03-23 | | | Snapshot as of 2020-06-01 | 2020-06-01 | 2026-03-23 | | | Snapshot as of 2020-05-01 | 2020-05-01 | 2026-03-23 | | | Snapshot as of 2020-04-01 | 2020-04-01 | 2026-03-23 | | | Snapshot as of 2020-03-01 | 2020-03-01 | 2026-03-23 | |
Show 72 earlier file versions | Reporting period | CMS published | Loaded | Latest file | | ------------------------- | ------------- | ---------- | ----------- | | Snapshot as of 2020-02-01 | 2020-02-01 | 2026-03-23 | | | Snapshot as of 2020-01-01 | 2020-01-01 | 2026-03-23 | | | Snapshot as of 2025-12-01 | 2025-12-01 | 2026-02-28 | | | Snapshot as of 2025-11-01 | 2025-11-01 | 2026-02-28 | | | Snapshot as of 2025-10-01 | 2025-10-01 | 2026-02-28 | | | Snapshot as of 2025-09-01 | 2025-09-01 | 2026-02-28 | | | Snapshot as of 2025-07-01 | 2025-07-01 | 2026-02-28 | | | Snapshot as of 2025-06-01 | 2025-06-01 | 2026-02-28 | | | Snapshot as of 2025-05-01 | 2025-05-01 | 2026-02-28 | | | Snapshot as of 2025-04-01 | 2025-04-01 | 2026-02-28 | | | Snapshot as of 2025-03-01 | 2025-03-01 | 2026-02-28 | | | Snapshot as of 2025-02-01 | 2025-02-01 | 2026-02-28 | | | Snapshot as of 2024-11-01 | 2024-11-01 | 2026-02-28 | | | Snapshot as of 2024-10-01 | 2024-10-01 | 2026-02-28 | | | Snapshot as of 2024-09-01 | 2024-09-01 | 2026-02-28 | | | Snapshot as of 2024-08-01 | 2024-08-01 | 2026-02-28 | | | Snapshot as of 2024-07-01 | 2024-07-01 | 2026-02-28 | | | Snapshot as of 2024-06-01 | 2024-06-01 | 2026-02-28 | | | Snapshot as of 2024-05-01 | 2024-05-01 | 2026-02-28 | | | Snapshot as of 2024-04-01 | 2024-04-01 | 2026-02-28 | | | Snapshot as of 2024-03-01 | 2024-03-01 | 2026-02-28 | | | Snapshot as of 2024-02-01 | 2024-02-01 | 2026-02-28 | | | Snapshot as of 2024-01-01 | 2024-01-01 | 2026-02-28 | | | Snapshot as of 2023-11-01 | 2023-11-01 | 2026-02-28 | | | Snapshot as of 2023-10-01 | 2023-10-01 | 2026-02-28 | | | Snapshot as of 2023-09-01 | 2023-09-01 | 2026-02-28 | | | Snapshot as of 2023-08-01 | 2023-08-01 | 2026-02-28 | | | Snapshot as of 2023-07-01 | 2023-07-01 | 2026-02-28 | | | Snapshot as of 2023-06-01 | 2023-06-01 | 2026-02-28 | | | Snapshot as of 2023-05-01 | 2023-05-01 | 2026-02-28 | | | Snapshot as of 2023-04-01 | 2023-04-01 | 2026-02-28 | | | Snapshot as of 2023-03-01 | 2023-03-01 | 2026-02-28 | | | Snapshot as of 2023-02-01 | 2023-02-01 | 2026-02-28 | | | Snapshot as of 2023-01-01 | 2023-01-01 | 2026-02-28 | | | Snapshot as of 2022-11-01 | 2022-11-01 | 2026-02-28 | | | Snapshot as of 2022-10-01 | 2022-10-01 | 2026-02-28 | | | Snapshot as of 2022-09-01 | 2022-09-01 | 2026-02-28 | | | Snapshot as of 2022-08-01 | 2022-08-01 | 2026-02-28 | | | Snapshot as of 2022-07-01 | 2022-07-01 | 2026-02-28 | | | Snapshot as of 2022-06-01 | 2022-06-01 | 2026-02-28 | | | Snapshot as of 2022-05-01 | 2022-05-01 | 2026-02-28 | | | Snapshot as of 2022-04-01 | 2022-04-01 | 2026-02-28 | | | Snapshot as of 2022-03-01 | 2022-03-01 | 2026-02-28 | | | Snapshot as of 2022-02-01 | 2022-02-01 | 2026-02-28 | | | Snapshot as of 2022-01-01 | 2022-01-01 | 2026-02-28 | | | Snapshot as of 2021-11-01 | 2021-11-01 | 2026-02-28 | | | Snapshot as of 2021-10-01 | 2021-10-01 | 2026-02-28 | | | Snapshot as of 2021-09-01 | 2021-09-01 | 2026-02-28 | | | Snapshot as of 2021-08-01 | 2021-08-01 | 2026-02-28 | | | Snapshot as of 2021-07-01 | 2021-07-01 | 2026-02-28 | | | Snapshot as of 2021-06-01 | 2021-06-01 | 2026-02-28 | | | Snapshot as of 2021-05-01 | 2021-05-01 | 2026-02-28 | | | Snapshot as of 2021-04-01 | 2021-04-01 | 2026-02-28 | | | Snapshot as of 2021-03-01 | 2021-03-01 | 2026-02-28 | | | Snapshot as of 2021-02-01 | 2021-02-01 | 2026-02-28 | | | Snapshot as of 2021-01-01 | 2021-01-01 | 2026-02-28 | | | Snapshot as of 2020-11-01 | 2020-11-01 | 2026-02-28 | | | Snapshot as of 2020-10-01 | 2020-10-01 | 2026-02-28 | | | Snapshot as of 2020-09-01 | 2020-09-01 | 2026-02-28 | | | Snapshot as of 2020-08-01 | 2020-08-01 | 2026-02-28 | | | Snapshot as of 2019-12-01 | 2019-12-01 | 2026-02-28 | | | Snapshot as of 2019-10-01 | 2019-10-01 | 2026-02-28 | | | Snapshot as of 2019-09-01 | 2019-09-01 | 2026-02-28 | | | Snapshot as of 2019-08-01 | 2019-08-01 | 2026-02-28 | | | Snapshot as of 2019-07-01 | 2019-07-01 | 2026-02-28 | | | Snapshot as of 2019-06-01 | 2019-06-01 | 2026-02-28 | | | Snapshot as of 2019-05-01 | 2019-05-01 | 2026-02-28 | | | Snapshot as of 2019-04-01 | 2019-04-01 | 2026-02-28 | | | Snapshot as of 2019-03-01 | 2019-03-01 | 2026-02-28 | | | Snapshot as of 2019-02-01 | 2019-02-01 | 2026-02-28 | | | Snapshot as of 2019-01-01 | 2019-01-01 | 2026-02-28 | | | Snapshot as of 2026-02-01 | 2026-02-01 | 2026-02-27 | |
## Data dictionary
📋 50 data columns + 6 lineage columns **Data columns** | Column | Type | Description | | ------------------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | `STATE_OR_NATION` | TEXT | State name (e.g., 'New York') or 'Nation' for the US national average row. Use WHERE state\_or\_nation = 'Nation' for national benchmarks. | | `OVERALL_RATING` | NUMBER | Average overall Five-Star rating for nursing homes in this state/nation | | `HEALTH_INSPECTION_RATING` | NUMBER | Average health inspection rating for nursing homes in this state/nation | | `QM_RATING` | NUMBER | Average quality measure rating for nursing homes in this state/nation | | `STAFFING_RATING` | NUMBER | Average staffing rating for nursing homes in this state/nation | | `CYCLE_1_TOTAL_NUMBER_OF_HEALTH_DEFICIENCIES` | NUMBER | Average total health deficiencies per facility in the most recent inspection cycle | | `CYCLE_1_TOTAL_NUMBER_OF_FIRE_SAFETY_DEFICIENCIES` | NUMBER | Average total fire safety deficiencies per facility in the most recent inspection cycle | | `CYCLE_2_TOTAL_NUMBER_OF_HEALTH_DEFICIENCIES` | NUMBER | Average total health deficiencies per facility in the second most recent inspection cycle | | `CYCLE_2_TOTAL_NUMBER_OF_FIRE_SAFETY_DEFICIENCIES` | NUMBER | Average total fire safety deficiencies per facility in the second most recent cycle | | `CYCLE_3_TOTAL_NUMBER_OF_HEALTH_DEFICIENCIES` | NUMBER | Average total health deficiencies per facility in the third most recent inspection cycle | | `CYCLE_3_TOTAL_NUMBER_OF_FIRE_SAFETY_DEFICIENCIES` | NUMBER | Average total fire safety deficiencies per facility in the third most recent cycle | | `AVERAGE_NUMBER_OF_RESIDENTS_PER_DAY` | NUMBER | Average daily census across all nursing homes in this state/nation | | `REPORTED_NURSE_AIDE_STAFFING_HOURS_PER_RESIDENT_PER_DAY` | NUMBER | Average CNA hours per resident per day across facilities in this state/nation | | `REPORTED_LPN_STAFFING_HOURS_PER_RESIDENT_PER_DAY` | NUMBER | Average LPN hours per resident per day | | `REPORTED_RN_STAFFING_HOURS_PER_RESIDENT_PER_DAY` | NUMBER | Average RN hours per resident per day | | `REPORTED_LICENSED_STAFFING_HOURS_PER_RESIDENT_PER_DAY` | NUMBER | Average total licensed nursing (RN + LPN) hours per resident per day | | `REPORTED_TOTAL_NURSE_STAFFING_HOURS_PER_RESIDENT_PER_DAY` | NUMBER | Average total nursing staff hours per resident per day | | `TOTAL_NURSE_STAFF_HOURS_PER_RESIDENT_PER_DAY_WEEKEND` | NUMBER | Average total nursing staff hours per resident per day on weekends | | `RN_HOURS_PER_RESIDENT_PER_DAY_WEEKEND` | NUMBER | Average RN hours per resident per day on weekends | | `REPORTED_PT_STAFFING_HOURS_PER_RESIDENT_PER_DAY` | NUMBER | Average physical therapist hours per resident per day | | `TOTAL_NURSING_STAFF_TURNOVER` | NUMBER | Average annual nursing staff turnover rate (percentage) across facilities | | `REGISTERED_NURSE_TURNOVER` | NUMBER | Average annual RN turnover rate (percentage) across facilities | | `NUMBER_OF_ADMINISTRATORS_WHO_HAVE_LEFT` | NUMBER | Average number of administrator departures per facility | | `NURSING_CASE_MIX_INDEX` | NUMBER | Average nursing case-mix index across facilities in this state/nation | | `CASE_MIX_RN_STAFFING_HOURS_PER_RESIDENT_PER_DAY` | NUMBER | Average case-mix adjusted RN hours per resident per day | | `CASE_MIX_TOTAL_NURSE_STAFFING_HOURS_PER_RESIDENT_PER_DAY` | NUMBER | Average case-mix adjusted total nursing hours per resident per day | | `CASE_MIX_WEEKEND_TOTAL_NURSE_STAFFING_HOURS_PER_RESIDENT_PER_DAY` | NUMBER | Average case-mix adjusted weekend total nursing hours per resident per day | | `NUMBER_OF_FINES` | NUMBER | Average number of fines per facility in this state/nation | | `FINE_AMOUNT_IN_DOLLARS` | NUMBER | Average total fine amount (dollars) per facility | | `PCT_LONG_STAY_NEED_HELP_DAILY_ACTIVITIES_INCREASED` | NUMBER | Average % of long-stay residents whose need for help with daily activities has increased | | `PCT_LONG_STAY_LOSE_TOO_MUCH_WEIGHT` | NUMBER | Average % of long-stay residents who lose too much weight | | `PCT_LONG_STAY_CATHETER` | NUMBER | Average % of long-stay residents with an indwelling catheter | | `PCT_LONG_STAY_UTI` | NUMBER | Average % of long-stay residents with a urinary tract infection | | `PCT_LONG_STAY_DEPRESSIVE_SYMPTOMS` | NUMBER | Average % of long-stay residents who have depressive symptoms | | `PCT_LONG_STAY_PHYSICALLY_RESTRAINED` | NUMBER | Average % of long-stay residents who were physically restrained | | `PCT_LONG_STAY_FALLS_MAJOR_INJURY` | NUMBER | Average % of long-stay residents experiencing one or more falls with major injury | | `PCT_LONG_STAY_PNEUMOCOCCAL_VACCINE` | NUMBER | Average % of long-stay residents assessed and appropriately given the pneumococcal vaccine | | `PCT_LONG_STAY_ANTIPSYCHOTIC` | NUMBER | Average % of long-stay residents who received an antipsychotic medication | | `PCT_LONG_STAY_WALK_WORSENED` | NUMBER | Average % of long-stay residents whose ability to walk independently worsened | | `PCT_LONG_STAY_ANTIANXIETY_HYPNOTIC` | NUMBER | Average % of long-stay residents who received an antianxiety or hypnotic medication | | `PCT_LONG_STAY_INFLUENZA_VACCINE` | NUMBER | Average % of long-stay residents assessed and appropriately given the seasonal influenza vaccine | | `PCT_LONG_STAY_PRESSURE_ULCERS` | NUMBER | Average % of long-stay residents with pressure ulcers | | `PCT_LONG_STAY_INCONTINENCE` | NUMBER | Average % of long-stay residents with new or worsened bowel or bladder incontinence | | `PCT_SHORT_STAY_PNEUMOCOCCAL_VACCINE` | NUMBER | Average % of short-stay residents assessed and given the pneumococcal vaccine | | `PCT_SHORT_STAY_ANTIPSYCHOTIC` | NUMBER | Average % of short-stay residents who newly received an antipsychotic medication | | `PCT_SHORT_STAY_REHOSPITALIZED` | NUMBER | Average % of short-stay residents who were rehospitalized after nursing home admission | | `PCT_SHORT_STAY_ED_VISIT` | NUMBER | Average % of short-stay residents who had an outpatient emergency department visit | | `HOSPITALIZATIONS_PER_1000_LONG_STAY_DAYS` | NUMBER | Average number of hospitalizations per 1,000 long-stay resident days | | `ED_VISITS_PER_1000_LONG_STAY_DAYS` | NUMBER | Average number of outpatient emergency department visits per 1,000 long-stay resident days | | `PROCESSING_DATE` | DATE | Date CMS processed/released this data snapshot | **Lineage columns** (present on every feed table) | Column | Type | Description | | -------------- | -------------- | -------------------------------------------- | | `ROW_ID` | TEXT | Unique row ID for this table (PK) | | `FILE_ID` | TEXT | Source file — joins to `FEEDS_FILES.ID` (FK) | | `FILE_FEED_ID` | TEXT | Parent feed — joins to `FEEDS.ID` (FK) | | `FILE_NAME` | TEXT | Source file name as published by CMS | | `ROWNUM` | NUMBER | Row number within the source file | | `CREATED_AT` | TIMESTAMP\_NTZ | Timestamp when the record was loaded |
## Row-level lineage Every row in this table traces to the exact CMS source file that produced it. The `FILE_ID` column joins to the `FEEDS_FILES` catalog table, and `FILE_FEED_ID` joins to the `FEEDS` master table: ```mermaid erDiagram FEEDS ||--o{ FEEDS_FILES : "ID = FEED_ID" FEEDS ||--o{ NURSING_HOMES_STATE_US_AVERAGES : "ID = FILE_FEED_ID" FEEDS_FILES ||--o{ NURSING_HOMES_STATE_US_AVERAGES : "ID = FILE_ID" FEEDS { text ID PK text TITLE text VIEW_NAME text ACCURAL_PERIODICITY } FEEDS_FILES { text ID PK text FEED_ID FK date TEMPORAL_START date TEMPORAL_END date CMS_FEED_MODIFIED number IS_LATEST } NURSING_HOMES_STATE_US_AVERAGES { text ROW_ID PK text FILE_ID FK text FILE_FEED_ID FK text STATE_OR_NATION number OVERALL_RATING number HEALTH_INSPECTION_RATING number QM_RATING number remaining_46_data_columns } ``` Trace any row back to its source file and reporting period: ```sql SELECT d.STATE_OR_NATION, d.OVERALL_RATING, d.HEALTH_INSPECTION_RATING, ff.TEMPORAL_START, ff.TEMPORAL_END, ff.CMS_FEED_MODIFIED FROM DWV.NURSING_HOMES_STATE_US_AVERAGES d JOIN DWV.FEEDS_FILES ff ON d.FILE_ID = ff.ID; ``` ## Source & provenance Published by the **Centers for Medicare & Medicaid Services** (bureau 009:38). * [Official CMS documentation](https://data.cms.gov/provider-data/topics/nursing-homes) * [Xcdc V8bm](https://data.cms.gov/provider-data/dataset/xcdc-v8bm) ## Frequently asked questions ### How often is Nursing Homes Including Rehab Services - State US Averages updated? Monthly. CMS last published this feed on 2026-06-01, and Dataplex loaded it to the warehouse on 2026-06-29. New releases are added automatically when CMS publishes them. ### What years does Nursing Homes Including Rehab Services - State US Averages cover? 2019 through 2026. ### How many records are in Nursing Homes Including Rehab Services - State US Averages? Count the current snapshot yourself once the share is mounted: ```sql SELECT COUNT(*) FROM DWV.NURSING_HOMES_STATE_US_AVERAGES d JOIN DWV.FEEDS_FILES ff ON d.FILE_ID = ff.ID WHERE ff.IS_LATEST = 1; ``` ### How do I get Nursing Homes Including Rehab Services - State US Averages data? It's included in the CMS Data Feeds Dataset on the [Snowflake Marketplace](https://app.snowflake.com/marketplace/listing/GZT1Z125KDH/dataplex-consulting-data-products-cms-data-feeds-dataset) (free trial available) and via [Databricks Delta Sharing](https://checkout.dataplex-consulting.com/b/3cIdR2e1J59Sh2w7pWbQY00). Once mounted, query `DWV.NURSING_HOMES_STATE_US_AVERAGES` directly — no pipeline setup required. ## Related feeds {% content-ref url="/pages/obaajvNljtwIE9uTCSHM" %} [Dialysis Facility - State Averages](/data-catalog/cms-data-feeds-dataset/cms-data-feeds-catalog/dialysis-facility-state-averages.md) {% endcontent-ref %} {% content-ref url="/pages/tHA84Kp2BFdlvJZLVuP9" %} [Nursing Homes Including Rehab Services - Medicare Claims Quality Measures](/data-catalog/cms-data-feeds-dataset/cms-data-feeds-catalog/nursing-homes-including-rehab-services-medicare-claims-quality-measures.md) {% endcontent-ref %} {% content-ref url="/pages/qVRif8sFR0Ev3LILJelc" %} [Nursing Homes Including Rehab Services - MDS Quality Measures](/data-catalog/cms-data-feeds-dataset/cms-data-feeds-catalog/nursing-homes-including-rehab-services-mds-quality-measures.md) {% endcontent-ref %} {% content-ref url="/pages/x3Nb1BlWbzlBdjcH6onF" %} [Dialysis Facility - National Averages](/data-catalog/cms-data-feeds-dataset/cms-data-feeds-catalog/dialysis-facility-national-averages.md) {% endcontent-ref %} {% content-ref url="/pages/f9nk6ZMu270siHqMNDJh" %} [Skilled Nursing Facility Quality Reporting Program - Provider Data](/data-catalog/cms-data-feeds-dataset/cms-data-feeds-catalog/skilled-nursing-facility-quality-reporting-program-provider-data.md) {% endcontent-ref %} ## Get this feed 1. [Start a free trial on Snowflake Marketplace](https://app.snowflake.com/marketplace/listing/GZT1Z125KDH/dataplex-consulting-data-products-cms-data-feeds-dataset) or purchase via [Databricks](https://checkout.dataplex-consulting.com/b/3cIdR2e1J59Sh2w7pWbQY00) 2. Mount the share — the database and `DWV` schema appear in your account immediately 3. Run the [sample query](#sample-queries) above — no ETL, no pipeline maintenance Questions about this feed? Contact us at . *** Part of the [CMS Data Feeds Dataset](/data-catalog/cms-data-feeds-dataset.md) — 280+ feeds · 245B+ records · updated daily. [Back to the full catalog →](/data-catalog/cms-data-feeds-dataset/cms-data-feeds-catalog.md#nursing-homes-including-rehab-services-state-us-averages) --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.dataplex-consulting.com/data-catalog/cms-data-feeds-dataset/cms-data-feeds-catalog/nursing-homes-including-rehab-services-state-us-averages.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.