{ "category": "Cubes", "display_name": "CUBEKPIMEMBER", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.CUBEKPIMEMBER", "implementation_state": { "answer_bank": null, "detail": "No catalogue row at this commit. Pivot tables are being implemented in full, and this function with them.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": false, "state": "refuses", "state_label": "Refuses or not implemented", "summary": "Not yet implemented", "workbook_corpus": null }, "implementations": [], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.CUBEKPIMEMBER.json", "name": "CUBEKPIMEMBER", "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\n- **`CUBEVALUE`** — the necessary partner. `CUBEKPIMEMBER` produces the coordinate; `CUBEVALUE`\n turns it into a number. Neither is useful alone for KPI reporting.\n- **`CUBEMEMBER`** — the general coordinate producer. `CUBEKPIMEMBER` is best read as a\n specialized `CUBEMEMBER` that knows the MDX shape of KPI components so the author does not\n have to write `KPIGoal(\"…\")` by hand.\n- **`CUBEMEMBERPROPERTY`** — also returns \"something attached to a member\", but terminally: a\n property is a value, a KPI component is a coordinate. The two are easy to confuse and behave\n oppositely downstream.\n\nOutside the family, the confusion is with PivotTable KPI display fields and with Power BI's KPI\nvisual. Those render KPIs; this function addresses them.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n- There is no kernel; the function is an MDX-shape helper over a cube metadata lookup.\n- Returning a *value* rather than a coordinate would be the natural, wrong simplification. It\n would make single cells look right and break every `CUBEVALUE` that references them.\n- The `KPIValue`-only-shows-`kpi_name` display rule means the displayed text is not a function\n of the arguments in a uniform way. An implementation reproducing display text needs that\n special case explicitly.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nThe cell displays text — the KPI name, or the name plus component, or the supplied `caption` —\nand carries the underlying member expression as its identity for consumption by `CUBEVALUE`.\nThe identity-versus-display split is the same one described on [`CUBEMEMBER`](FUNC.CUBEMEMBER.md).\n\nWhile the request is outstanding the cell displays `#GETTING_DATA…` — a transient\nextended-family placeholder catalogued in [the value universe](../model/01-value-universe.md),\nnot a failure.\n\nThe Handbook cannot say from documentation whether `kpi_property` accepts the enumerated\nconstant *names* as text in a formula or only the integers; Microsoft's table lists both\ncolumns without saying which is accepted where. That is a genuine ambiguity, not a stylistic\none, and it is listed as a probe below.\n\n\n\n### Errors\n\n\nAs documented by Microsoft on the page linked below:\n\n- **`#NAME?`** — the connection name is not a valid workbook connection; or the OLAP server is\n not running, not available, or returns an error message.\n- **`#N/A`** — `kpi_name` or `kpi_property` is invalid; or the expression refers to a\n session-scoped object whose PivotTable has been deleted or converted to formulas.\n\nNote that an invalid *component selector* and an invalid *KPI name* collapse onto the same\ncode, so `#N/A` here does not tell a workbook author which of the two arguments is wrong.\n\n\n", "sources": "- Microsoft, \"CUBEKPIMEMBER function\" —\n \n (syntax, all four arguments, the complete six-row `kpi_property` table with its integers and\n enumerated constants, the `KPIValue` display rule, the instruction to use the result as a\n `CUBEVALUE` argument, the `#GETTING_DATA` remark, and the `#NAME?` and `#N/A` conditions).\n- Microsoft, \"CUBEVALUE function\" —\n \n (the consumer side of the two-function pattern).\n- Handbook `data/presence/FUNC.CUBEKPIMEMBER.json` — no implementation module, no dispatch\n entry.\n- Handbook `content/model/01-value-universe.md` — the extended error-code family.\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": "\nA KPI in an OLAP cube is not a number. It is a small bundle of related expressions — an actual\nvalue, a target, a status, a trend, a weight, and a time context — defined once by whoever\nbuilt the cube. `CUBEKPIMEMBER` selects **one component of that bundle** and hands back a member\nexpression naming it.\n\n\n`CUBEKPIMEMBER(connection, kpi_name, kpi_property, [caption])` resolves the named KPI against\nthe cube and returns the member corresponding to the requested component.\n\nThe crucial point — and the one that makes the function make sense — is that **the result is a\ncoordinate, not a value**. Microsoft states the usage rule directly: \"to use the KPI in a\ncalculation, specify the CUBEKPIMEMBER function as a member_expression argument in the CUBEVALUE\nfunction.\" A bare `CUBEKPIMEMBER` cell displays the KPI's name; it does not display the KPI's\nnumber. Getting the number takes two functions.\n\nThat is the design the whole family shares (`CUBEMEMBER` addresses, `CUBEVALUE` fetches), but\nit surprises people here more than anywhere else, because a \"KPI\" sounds like a value by name.\n\nThe six components Microsoft documents:\n\n| Integer | Constant | What it names |\n|---|---|---|\n| 1 | `KPIValue` | the actual value |\n| 2 | `KPIGoal` | a target value |\n| 3 | `KPIStatus` | the state of the KPI at a specific moment in time |\n| 4 | `KPITrend` | a measure of the value over time |\n| 5 | `KPIWeight` | a relative importance assigned to the KPI |\n| 6 | `KPICurrentTimeMember` | a temporal context for the KPI |\n\n`KPIStatus` and `KPITrend` are the two whose *scale* is a cube convention rather than an Excel\none: they are typically normalized indicator values, and a workbook that treats them as\ncurrency or as raw counts will render nonsense. `KPICurrentTimeMember` is different in kind\nfrom the other five — it names a time member rather than a numeric component, which is what\nmakes \"compare this KPI against the same period last year\" expressible.\n\n\n\n### Arguments\n\n\n- **`connection`** (required) — text; the name of a connection stored in the workbook, used as\n a lookup key rather than as a connection string.\n- **`kpi_name`** (required) — text; the KPI's name as defined in the cube. Cube metadata, not a\n label of the workbook's choosing.\n- **`kpi_property`** (required) — the component selector from the table above. Microsoft\n documents both integers and enumerated-constant names. Note that this argument is *required*,\n which means there is no \"just give me the KPI\" call — you must always choose a component.\n- **`caption`** (optional) — alternative text displayed instead of `kpi_name` and\n `kpi_property`.\n\nOne display detail Microsoft records and which is easy to trip over: if `kpi_property` is\n`KPIValue`, **only `kpi_name` is displayed** in the cell. So the `KPIValue` cell and a\n`KPIGoal` cell for the same KPI look different by default, and the difference is a display\nconvention rather than a difference in what the cells are.\n\n\n" }, "signature": { "display": "CUBEKPIMEMBER(connection, kpi_name, kpi_property, [caption])", "parameters": [ { "description": null, "name": "connection", "optional": false, "repeats": false }, { "description": null, "name": "kpi_name", "optional": false, "repeats": false }, { "description": null, "name": "kpi_property", "optional": false, "repeats": false }, { "description": null, "name": "caption", "optional": true, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "not_implemented", "reason": "No catalogue row at this commit. Pivot tables are being implemented in full, and this function with them." }, "arity": { "max": 4, "min": 3 }, "category": "Cubes", "classification": {}, "descriptions": { "long": null, "short": "A key performance indicator property of an OLAP cube", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns a key performance indicator (KPI) property and displays the KPI name in the cell. A KPI is a quantifiable measurement, such as monthly gross profit or quarterly employee turnover, that is used to monitor an organization's performance.", "microsoft_url": "https://support.microsoft.com/en-us/office/cubekpimember-function-744608bf-2c62-42cd-b67a-a56109f4b03b" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "CUBEKPIMEMBER" }, { "locale": "bg-BG", "name": "CUBEKPIMEMBER" }, { "locale": "cs-CZ", "name": "CUBEKPIMEMBER" }, { "locale": "da-DK", "name": "KUBE.KPI.MEDLEM" }, { "locale": "de-DE", "name": "CUBEKPIMEMBER" }, { "locale": "el-GR", "name": "CUBEKPIMEMBER" }, { "locale": "en-AU", "name": "CUBEKPIMEMBER" }, { "locale": "en-GB", "name": "CUBEKPIMEMBER" }, { "locale": "en-US", "name": "CUBEKPIMEMBER" }, { "locale": "es-ES", "name": "MIEMBROKPICUBO" }, { "locale": "et-EE", "name": "CUBEKPIMEMBER" }, { "locale": "fi-FI", "name": "KUUTIOKPIJÄSEN" }, { "locale": "fr-FR", "name": "MEMBREKPICUBE*" }, { "locale": "he-IL", "name": "CUBEKPIMEMBER" }, { "locale": "hr-HR", "name": "CUBEKPIMEMBER" }, { "locale": "hu-HU", "name": "KOCKA.FŐTELJMUT" }, { "locale": "id-ID", "name": "CUBEKPIMEMBER" }, { "locale": "it-IT", "name": "CUBEKPIMEMBER" }, { "locale": "ja-JP", "name": "CUBEKPIMEMBER" }, { "locale": "ko-KR", "name": "CUBEKPIMEMBER" }, { "locale": "lt-LT", "name": "CUBEKPIMEMBER" }, { "locale": "lv-LV", "name": "CUBEKPIMEMBER" }, { "locale": "nb-NO", "name": "CUBEKPIMEMBER" }, { "locale": "nl-NL", "name": "KUBUSKPILID" }, { "locale": "pl-PL", "name": "ELEMENT.KPI.MODUŁU" }, { "locale": "pt-BR", "name": "CUBEKPIMEMBER" }, { "locale": "pt-PT", "name": "MEMBROKPICUBO" }, { "locale": "ro-RO", "name": "CUBEKPIMEMBER" }, { "locale": "ru-RU", "name": "КУБЭЛЕМЕНТКИП" }, { "locale": "sk-SK", "name": "CUBEKPIMEMBER" }, { "locale": "sl-SI", "name": "CUBEKPIMEMBER" }, { "locale": "sr-Latn-RS", "name": "CUBEKPIMEMBER" }, { "locale": "sv-SE", "name": "KUBKPIMEDLEM" }, { "locale": "th-TH", "name": "CUBEKPIMEMBER" }, { "locale": "tr-TR", "name": "KÜPKPIÜYESİ işlevi" }, { "locale": "uk-UA", "name": "CUBEKPIMEMBER" }, { "locale": "vi-VN", "name": "CUBEKPIMEMBER" }, { "locale": "zh-CN", "name": "CUBEKPIMEMBER" }, { "locale": "zh-HK", "name": "CUBEKPIMEMBER" }, { "locale": "zh-TW", "name": "CUBEKPIMEMBER" } ], "signature": { "display": "CUBEKPIMEMBER(connection, kpi_name, kpi_property, [caption])", "parameters": [ { "description": null, "name": "connection", "optional": false, "repeats": false }, { "description": null, "name": "kpi_name", "optional": false, "repeats": false }, { "description": null, "name": "kpi_property", "optional": false, "repeats": false }, { "description": null, "name": "caption", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "CUBEKPIMEMBER", "version_marker": null, "xlcall": { "code": "477", "symbol": "xlfCubekpimember" } }, "microsoft": "https://support.microsoft.com/en-us/office/cubekpimember-function-744608bf-2c62-42cd-b67a-a56109f4b03b" }, "try_it": { "formula": "=CUBEKPIMEMBER(\"ThisWorkbookDataModel\",\"Sales\",1)", "note": "This example needs an Excel cube connection. OneCalc cannot provide that connection in this preview.", "preview_status": "refused" }, "url": "https://handbook.dnacalc.com/functions/CUBEKPIMEMBER.html", "variants": [], "versions": [] }