{
  "category": "Lookup and reference functions",
  "display_name": "GETPIVOTDATA",
  "entry_kind": "built_in_function",
  "eval_api": {
    "method": "POST",
    "url": "https://handbook.dnacalc.com/api/eval"
  },
  "function_id": "FUNC.GETPIVOTDATA",
  "implementation_state": {
    "answer_bank": null,
    "detail": "The catalogue row declines every call until pivot tables land; they are being implemented in full, and this function with them.",
    "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87",
    "in_catalogue": true,
    "state": "refuses",
    "state_label": "Refuses or not implemented",
    "summary": "Refuses all 2 recorded calls",
    "workbook_corpus": {
      "cells": 2,
      "refused": 2
    }
  },
  "implementations": [
    {
      "commit": "9e1884369a678158dd82d3d74188daf986995e87",
      "flavour": "excel-compatibility-candidate",
      "language": "Rust",
      "name": "CalcFunc",
      "own_code": [
        "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/host_facts.rs#L453-L455"
      ],
      "repository": "https://github.com/DnaCalc/DnaCalc",
      "shared_code": [],
      "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/host_facts.rs#L453-L455",
      "state": "refuses",
      "suite": null,
      "summary": "Refuses all 2 recorded calls"
    }
  ],
  "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.GETPIVOTDATA.json",
  "name": "GETPIVOTDATA",
  "notes": [],
  "schema": "efh.function-reference/v1",
  "section_order": [
    "what-it-does",
    "try-it",
    "quirks",
    "how-to-implement",
    "version-differences",
    "alternatives"
  ],
  "sections": {
    "alternatives": "\n### Relationships\n\n- **`CUBEVALUE` / `CUBEMEMBER`** and the rest of the cube family are the OLAP-native way of\n  asking the same kind of dimensional question, without a PivotTable in between.\n- **`SUMIFS` / `COUNTIFS` / `AVERAGEIFS`** query the *source* data with criteria and are the\n  usual alternative when the PivotTable is only there as an intermediary. They see filtered-out\n  rows, which `GETPIVOTDATA` does not — sometimes a feature, sometimes a bug.\n- **`INDEX`/`MATCH` over the PivotTable's cells** is what people do when they turn off\n  automatic `GETPIVOTDATA` generation. It is positional and therefore fragile in exactly the\n  way `GETPIVOTDATA` avoids.\n- The `Generate GetPivotData` toggle is the reason most readers meet this function; it is a UI\n  setting, not a function argument.\n\n\n",
    "how-to-implement": "\n### Notes for implementers\n\n- This function cannot be implemented in the function layer. It requires a PivotTable object\n  model — fields, items, hierarchies, active filters, visibility, and the cache behind them —\n  which is workbook state, not evaluation state. Any implementation is really an implementation\n  of that model with a thin lookup on top.\n- The query is by *name*, not by position, and names are matched against the report's current\n  configuration. Visibility is part of the match: an invisible field is not merely empty, it is\n  `#REF!`.\n- Date and time items must be handled as serial numbers to stay locale-portable. An\n  implementation that accepts date strings will produce workbooks that break when opened\n  elsewhere.\n- The `pivot_table` argument must be resolved to a table identity, not dereferenced to a value.\n\n\n",
    "quirks": "\n### Why this entry does not calculate yet\n\n\nThe catalogue has a row for `GETPIVOTDATA`, and the row declines every call. PivotTables are being\nimplemented in full, and this function with them; the state at the top of this page comes from the\npinned commit and changes when that code lands.\n\nThe reason is layering rather than difficulty. Every other function\nin this Handbook's lookup-and-reference category can be described as a computation over values\nand addresses. `GETPIVOTDATA` cannot: its arguments are coordinates in a *PivotTable's* model —\nfields, items, hierarchies, filters, visibility — and that model is a workbook object with its\nown cache, its own refresh lifecycle, and its own source (a range, an external query, or an\nOLAP cube). A function evaluator that owns none of that has nothing to query.\n\n- the Handbook's uniform behavioural battery records every probe row as **not dispatchable** —\n  `cannot-call:not-in-reference-catalog`;\n- the entry has **no implementing module**, and therefore no family.\n\nThis is the honest state, and the Handbook publishes it as such: a real entry, with real\ndocumented semantics, and no implementation behind it.\n\n\n\n### Result and edge cases\n\n\nThe return kind is whatever the PivotTable's value field holds at the queried coordinate —\nalmost always a number, since value fields are aggregates, but a text or error value is\npossible depending on the source and the aggregation.\n\n- **A query with no pairs** returns the grand total.\n- **Multiple items for one field** narrow to the union of those items, subject to how the\n  PivotTable aggregates them.\n- **Calculated fields and calculated items** are part of the PivotTable's model and are\n  queryable by name like any other field, but what they return depends on the PivotTable's own\n  calculation semantics rather than on `GETPIVOTDATA`.\n- **The layout is irrelevant.** Collapsing an outline, moving a field from rows to columns, or\n  re-sorting does not change what a given `GETPIVOTDATA` call returns — which is the whole\n  point.\n- **Refresh does change it**, because the underlying data changed.\n\n\n\n### Errors\n\n\nMicrosoft documents `#REF!` for this function, with three stated causes:\n\n| Error | Documented condition |\n|---|---|\n| `#REF!` | The arguments describe a field that is not visible |\n| `#REF!` | A report filter excludes the requested data |\n| `#REF!` | The `pivot_table` argument is not an actual PivotTable range |\n\nThe first two are the ones that surprise. `GETPIVOTDATA` reads the *report*, not the source\ndata: a value that exists in the source but is filtered out of the current view is not\nretrievable, and a field that has been removed from the layout is not retrievable either. A\nformula that worked yesterday can return `#REF!` today because someone collapsed a field —\nwhich is a different fragility from the one `GETPIVOTDATA` was built to remove, and worth\nknowing about before adopting it wholesale.\n\n\n",
    "sources": "\n- Microsoft, *GETPIVOTDATA function* —\n  <https://support.microsoft.com/en-us/office/getpivotdata-function-8c083b99-a922-4ca0-af5e-3af55960761f>\n  (syntax, `data_field` and `pivot_table` meanings, the up-to-126 field/item pairs and their\n  order-independence, brace syntax for multiple items, OLAP hierarchical item names, the\n  requirement that dates and times be serial numbers or `DATE`/`TIME` results, the three\n  `#REF!` conditions, and the automatic-generation behaviour with its **PivotTable Analyze ▸\n  Options ▸ Generate GetPivotData** toggle). Retrieved for this page.\n- Handbook `data/battery/FUNC.GETPIVOTDATA.json` — every probe row\n  `cannot-call:not-in-reference-catalog`.\n- Handbook `data/presence/FUNC.GETPIVOTDATA.json` — no implementing module, hence no family.\n- Handbook `content/model/03-call-pipeline.md` (the boundary between function semantics and\n  host/workbook obligations).\n\n",
    "version-differences": "No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.",
    "what-it-does": "\n`GETPIVOTDATA` queries a PivotTable. It does not read a cell; it names a *cell of a report* by\nits coordinates in the report's own dimensional language, and returns whatever aggregate sits\nthere.\n\nThe query has two parts:\n\n1. **Which report, and which measure.** `data_field` names a value field of the PivotTable —\n   the aggregate being read, as a text name. `pivot_table` is a reference to any cell inside\n   the PivotTable, used purely to identify the table; its address is not the address of the\n   answer.\n2. **Which cell of that report.** Zero or more `field`/`item` pairs each fix one dimension:\n   \"the `Region` field at item `North`\", \"the `Month` field at item `Mar`\". Microsoft documents\n   up to 126 pairs. The pairs may appear in any order, because they are named coordinates\n   rather than positional ones. Multiple items for one field are given in braces\n   (`{\"Mar\",\"Apr\"}`), and OLAP sources may use hierarchical item names such as\n   `\"[Product].[All Products].[Foods].[Baked Goods]\"`.\n\nWith no pairs, the result is the grand total for `data_field`. Each pair narrows the query one\ndimension further.\n\nThe design intent is worth stating because it is routinely resented: `GETPIVOTDATA` exists so\nthat a formula referring to a PivotTable keeps meaning the same thing when the PivotTable is\nrefreshed, re-sorted, or re-laid-out. A plain `=D7` breaks the moment a row is added upstream.\n`GETPIVOTDATA(\"Sales\", $A$3, \"Region\", \"North\")` does not, because it names the data rather\nthan its position. That is also why Excel *generates* these formulas automatically when you\ntype `=` and click a PivotTable cell — behaviour that can be turned off under **PivotTable\nAnalyze ▸ Options ▸ Generate GetPivotData**, and which is the single most common reason readers\nencounter this function without having chosen it.\n\n\n\n### Arguments\n\n\nMicrosoft documents\n`GETPIVOTDATA(data_field, pivot_table, [field1, item1, field2, item2], …)`.\n\n**`data_field`** — required, text, quoted. The name of the PivotTable's value field.\n\n**`pivot_table`** — required. A reference to any cell, range, or named range **within** the\nPivotTable. It identifies which table to query, nothing more. Passing a reference that is not\ninside a PivotTable is an error.\n\n**`field`/`item` pairs** — optional and repeating, up to 126 pairs. Field names and non-numeric,\nnon-date items are quoted. Two points that catch people:\n\n- **Dates and times must be expressed as serial numbers or built with `DATE`/`TIME`.**\n  Microsoft is explicit about this, and the reason is locale: a quoted date string means\n  different things on different machines, so a workbook written in one locale would query the\n  wrong item in another. `DATE(1999,3,5)` and `36224` are portable; `\"3/5/1999\"` is not.\n- **The pairs are unordered**, which means there is no positional discipline to lean on and a\n  misspelled field name is a runtime failure rather than a shifted argument.\n\n\n"
  },
  "signature": {
    "display": "GETPIVOTDATA(data_field, pivot_table, [field1], [item1], ...)",
    "parameters": [
      {
        "description": null,
        "name": "data_field",
        "optional": false,
        "repeats": false
      },
      {
        "description": null,
        "name": "pivot_table",
        "optional": false,
        "repeats": false
      },
      {
        "description": null,
        "name": "field1",
        "optional": true,
        "repeats": false
      },
      {
        "description": null,
        "name": "item1",
        "optional": true,
        "repeats": true
      }
    ],
    "trailing_repeats": true
  },
  "sources": {
    "metadata": {
      "admission": {
        "label": "not_modelled",
        "reason": "The catalogue row declines every call until pivot tables land; they are being implemented in full, and this function with them."
      },
      "arity": {
        "max": 254,
        "min": 2
      },
      "category": "Lookup and reference functions",
      "classification": {},
      "descriptions": {
        "long": null,
        "short": "A value read out of a PivotTable report",
        "short_source": "dna-calc-own"
      },
      "docs": {
        "english_description": "Returns data stored in a PivotTable report",
        "microsoft_url": "https://support.microsoft.com/en-us/office/getpivotdata-function-8c083b99-a922-4ca0-af5e-3af55960761f"
      },
      "entry_kind": "built_in_function",
      "localized_family_names": null,
      "localized_names": [
        {
          "locale": "ar-SA",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "bg-BG",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "cs-CZ",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "da-DK",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "de-DE",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "el-GR",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "en-AU",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "en-GB",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "en-US",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "es-ES",
          "name": "IMPORTARDATOSDINAMICOS"
        },
        {
          "locale": "et-EE",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "fi-FI",
          "name": "NOUDA.PIVOT.TIEDOT"
        },
        {
          "locale": "fr-FR",
          "name": "GETPIVOTDATALIREDONNEESTABCROISDYNAMIQUE*"
        },
        {
          "locale": "he-IL",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "hr-HR",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "hu-HU",
          "name": "KIMUTATÁSADATOT.VESZ"
        },
        {
          "locale": "id-ID",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "it-IT",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "ja-JP",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "ko-KR",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "lt-LT",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "lv-LV",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "nb-NO",
          "name": "HENTPIVOTDATA"
        },
        {
          "locale": "nl-NL",
          "name": "DRAAITABEL.OPHALEN"
        },
        {
          "locale": "pl-PL",
          "name": "WEŹDANETABELI"
        },
        {
          "locale": "pt-BR",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "pt-PT",
          "name": "OBTERDADOSDIN"
        },
        {
          "locale": "ro-RO",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "ru-RU",
          "name": "ПОЛУЧИТЬ.ДАННЫЕ.СВОДНОЙ.ТАБЛИЦЫ"
        },
        {
          "locale": "sk-SK",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "sl-SI",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "sr-Latn-RS",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "sv-SE",
          "name": "HÄMTA.PIVOTDATA"
        },
        {
          "locale": "th-TH",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "tr-TR",
          "name": "ÖZETVERİAL işlevi"
        },
        {
          "locale": "uk-UA",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "vi-VN",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "zh-CN",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "zh-HK",
          "name": "GETPIVOTDATA"
        },
        {
          "locale": "zh-TW",
          "name": "GETPIVOTDATA"
        }
      ],
      "signature": {
        "display": "GETPIVOTDATA(data_field, pivot_table, [field1], [item1], ...)",
        "parameters": [
          {
            "description": null,
            "name": "data_field",
            "optional": false,
            "repeats": false
          },
          {
            "description": null,
            "name": "pivot_table",
            "optional": false,
            "repeats": false
          },
          {
            "description": null,
            "name": "field1",
            "optional": true,
            "repeats": false
          },
          {
            "description": null,
            "name": "item1",
            "optional": true,
            "repeats": true
          }
        ],
        "trailing_repeats": true
      },
      "surface_name": "GETPIVOTDATA",
      "version_marker": null,
      "xlcall": {
        "code": "358",
        "symbol": "xlfGetpivotdata"
      }
    },
    "microsoft": "https://support.microsoft.com/en-us/office/getpivotdata-function-8c083b99-a922-4ca0-af5e-3af55960761f"
  },
  "try_it": {
    "formula": "=GETPIVOTDATA(\"Sales\",B2)",
    "inputs": {
      "B2": 1
    },
    "note": "This example needs a worksheet PivotTable. OneCalc has no PivotTable in this preview.",
    "preview_status": "refused"
  },
  "url": "https://handbook.dnacalc.com/functions/GETPIVOTDATA.html",
  "variants": [],
  "versions": []
}