{ "category": "Cubes", "display_name": "CUBEVALUE", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.CUBEVALUE", "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.CUBEVALUE.json", "name": "CUBEVALUE", "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` is the consumer at the end of the family's pipeline; the other six functions\nproduce the coordinates it reads:\n\n- `CUBEMEMBER` and `CUBERANKEDMEMBER` produce single members or tuples.\n- `CUBESET` produces a set, which `CUBEVALUE` will aggregate across.\n- `CUBEKPIMEMBER` produces a KPI component; Microsoft's documented way to use a KPI in a\n calculation is to pass `CUBEKPIMEMBER` as a `member_expression` argument to `CUBEVALUE`.\n- `CUBESETCOUNT` and `CUBEMEMBERPROPERTY` are terminal — they return counts and properties\n and are not fed back into `CUBEVALUE`.\n\nThe function readers confuse with this one is `GETPIVOTDATA`, which extracts a value from a\nPivotTable already rendered on a sheet. `CUBEVALUE` talks to the cube and needs no PivotTable.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n- There is no numeric kernel here at all. The interesting work is MDX construction, connection\n resolution, and asynchronous retrieval; the arithmetic belongs to the server.\n- The null-to-empty-text conversion is a deliberate representational choice with a large blast\n radius. Any implementation that maps SQL/MDX null to numeric zero will silently produce\n different totals from Excel, and any implementation that maps it to a genuine blank will\n behave differently under `ISTEXT`. The documented behaviour is neither: it is a zero-length\n *string*.\n- Argument-position identity (MDX expression versus displayed value for referenced cells) must\n be resolved before the request is built, which means the evaluator has to be able to see the\n formula behind a referenced cell, not only its value. That is unusual for a worksheet\n function and does not fit the ordinary values-only argument-preparation profile described in\n [the call pipeline](../model/03-call-pipeline.md).\n- Retrieval is asynchronous with a visible intermediate state. Recalculation semantics — when\n a cell re-requests, what happens to dependents while `#GETTING_DATA` is showing — are host\n behaviour, not function semantics.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nThe published result is normally a number. Two edges deserve naming:\n\n- **Nulls arrive as empty text.** Microsoft documents that database null values are converted\n to zero-length strings, and explicitly recommends guarding dependent formulas with `IF` and\n `ISTEXT` so that arithmetic downstream does not fail. This is the single most consequential\n edge case on the page: a cell that *looks* blank is text, not a number, and it will turn\n `A1*2` into `#VALUE!`. The Handbook's coercion chapter explains why — text that does not read\n as a number is a named conversion failure, not a silent zero. See\n [coercion and lifting](../model/02-coercion-and-lifting.md).\n- **`#GETTING_DATA` while the request is outstanding.** The cell temporarily displays\n `#GETTING_DATA…` before the data arrives. It is one of the extended error codes catalogued in\n [the value universe](../model/01-value-universe.md) — a transient placeholder, not a failure.\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. As with the rest of the family, a\n naming failure and a connectivity failure share one code.\n- **`#VALUE!`** — at least one element within the tuple is invalid.\n- **`#N/A`** — the `member_expression` syntax is incorrect; the named member does not exist in\n the cube; the tuple is invalid because there is no intersection for the specified values\n (which Microsoft notes \"can occur with multiple elements from the same hierarchy\"); the set\n contains at least one member with a different dimension than the others; or the expression\n refers to a session-scoped calculated member or named set whose PivotTable has been deleted\n or converted to formulas.\n\nNone of these has been observed by the Handbook against a live Excel build. They are reported\nas documented behaviour, with the source named.\n\n\n", "sources": "- Microsoft, \"CUBEVALUE function\" —\n \n (syntax, the slicer framing, default-measure rule, the MDX-versus-displayed-value rule for\n cell references, the null-to-zero-length-string conversion and its `IF`/`ISTEXT` guard, and\n every error condition listed above).\n- Microsoft, \"CUBEKPIMEMBER function\" —\n \n (the documented route for using a KPI in a calculation via `CUBEVALUE`).\n- Handbook `data/presence/FUNC.CUBEVALUE.json` — no implementation module, no dispatch entry.\n- Handbook `content/model/01-value-universe.md` and `content/model/02-coercion-and-lifting.md`\n — the extended error-code family and the text-that-is-not-a-number conversion rule.\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`CUBEVALUE` names a point (or a region) of a cube by intersecting a list of member expressions,\nand asks the cube for the aggregated measure value at that intersection.\n\nThe mental model that makes the argument list intelligible: each `member_expression` is a\n**slicer**. Every argument you supply constrains one hierarchy; every hierarchy you leave\nunconstrained is aggregated over at its default (usually the \"All\" member). So\n`CUBEVALUE(conn, \"[Measures].[Sales]\", \"[Time].[2024]\")` means *sales, in 2024, summed over\neverything else* — the aggregation is not something `CUBEVALUE` performs, it is what the cube\nalready holds along the axes you did not pin.\n\nTwo consequences follow directly:\n\n1. **Order does not carry meaning; hierarchy membership does.** The arguments are a set of\n constraints, not a positional coordinate vector. Two expressions drawn from the *same*\n hierarchy do not narrow — they contradict, and produce an empty intersection.\n2. **A missing measure is not an error.** Microsoft documents that if no measure appears in any\n `member_expression`, the cube's default measure is used. A formula can therefore be\n perfectly valid, return a number, and be measuring something the author never named.\n\nAn argument may also be a `CUBESET` result rather than a single member. In that case the slice\nis the whole set and the cube aggregates across it — which is how `CUBEVALUE` produces subtotals\nover arbitrary member collections.\n\n\n\n### Arguments\n\n\n`CUBEVALUE(connection, [member_expression1], [member_expression2], …)`\n\n- **`connection`** (required) — text; the name of a connection *stored in the workbook*. Not a\n connection string, not a server name. Because it is a lookup key, a wrong name fails as\n `#NAME?`.\n- **`member_expression1`, `member_expression2`, …** (optional, repeating) — each is text\n holding an MDX expression evaluating to a member or a tuple, or a reference to a cell\n containing a `CUBESET` or other CUBE function.\n\nThe argument position most commonly misunderstood is any `member_expression` given as a **cell\nreference**. Microsoft states the rule plainly: if the referenced cell contains a CUBE function,\n`CUBEVALUE` uses that cell's MDX expression, *not* the value displayed in it. So a grid of\n`CUBEMEMBER` headers works as an addressing layer, while a cell containing the plain text\n`\"Sales\"` — which looks identical to a reader — does not.\n\nOmitting *all* member expressions is legal and asks for the cube's default measure at its\ndefault coordinates.\n\n\n" }, "signature": { "display": "CUBEVALUE(connection, [member_expression1], [member_expression2], ...)", "parameters": [ { "description": null, "name": "connection", "optional": false, "repeats": false }, { "description": null, "name": "member_expression1", "optional": true, "repeats": false }, { "description": null, "name": "member_expression2", "optional": true, "repeats": true } ], "trailing_repeats": true }, "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": 255, "min": 1 }, "category": "Cubes", "classification": {}, "descriptions": { "long": null, "short": "An aggregated value from an OLAP cube", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns an aggregated value from the cube.", "microsoft_url": "https://support.microsoft.com/en-us/office/cubevalue-function-8733da24-26d1-4e34-9b3a-84a8f00dcbe0" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "CUBEVALUE" }, { "locale": "bg-BG", "name": "CUBEVALUE" }, { "locale": "cs-CZ", "name": "CUBEVALUE" }, { "locale": "da-DK", "name": "KUBEVÆRDI" }, { "locale": "de-DE", "name": "CUBEVALUE" }, { "locale": "el-GR", "name": "CUBEVALUE" }, { "locale": "en-AU", "name": "CUBEVALUE" }, { "locale": "en-GB", "name": "CUBEVALUE" }, { "locale": "en-US", "name": "CUBEVALUE" }, { "locale": "es-ES", "name": "VALORCUBO" }, { "locale": "et-EE", "name": "CUBEVALUE" }, { "locale": "fi-FI", "name": "KUUTIONARVO" }, { "locale": "fr-FR", "name": "VALEURCUBE*" }, { "locale": "he-IL", "name": "CUBEVALUE" }, { "locale": "hr-HR", "name": "CUBEVALUE" }, { "locale": "hu-HU", "name": "KOCKA.ÉRTÉK" }, { "locale": "id-ID", "name": "CUBEVALUE" }, { "locale": "it-IT", "name": "CUBEVALUE" }, { "locale": "ja-JP", "name": "CUBEVALUE" }, { "locale": "ko-KR", "name": "CUBEVALUE" }, { "locale": "lt-LT", "name": "CUBEVALUE" }, { "locale": "lv-LV", "name": "CUBEVALUE" }, { "locale": "nb-NO", "name": "CUBEVALUE" }, { "locale": "nl-NL", "name": "KUBUSWAARDE" }, { "locale": "pl-PL", "name": "WARTOŚĆ.MODUŁU" }, { "locale": "pt-BR", "name": "CUBEVALUE" }, { "locale": "pt-PT", "name": "VALORCUBO" }, { "locale": "ro-RO", "name": "CUBEVALUE" }, { "locale": "ru-RU", "name": "КУБЗНАЧЕНИЕ" }, { "locale": "sk-SK", "name": "CUBEVALUE" }, { "locale": "sl-SI", "name": "CUBEVALUE" }, { "locale": "sr-Latn-RS", "name": "CUBEVALUE" }, { "locale": "sv-SE", "name": "KUBVÄRDE" }, { "locale": "th-TH", "name": "CUBEVALUE" }, { "locale": "tr-TR", "name": "KÜPDEĞERİ işlevi" }, { "locale": "uk-UA", "name": "CUBEVALUE" }, { "locale": "vi-VN", "name": "CUBEVALUE" }, { "locale": "zh-CN", "name": "CUBEVALUE" }, { "locale": "zh-HK", "name": "CUBEVALUE" }, { "locale": "zh-TW", "name": "CUBEVALUE" } ], "signature": { "display": "CUBEVALUE(connection, [member_expression1], [member_expression2], ...)", "parameters": [ { "description": null, "name": "connection", "optional": false, "repeats": false }, { "description": null, "name": "member_expression1", "optional": true, "repeats": false }, { "description": null, "name": "member_expression2", "optional": true, "repeats": true } ], "trailing_repeats": true }, "surface_name": "CUBEVALUE", "version_marker": null, "xlcall": { "code": "380", "symbol": "xlfCubevalue" } }, "microsoft": "https://support.microsoft.com/en-us/office/cubevalue-function-8733da24-26d1-4e34-9b3a-84a8f00dcbe0" }, "try_it": { "formula": "=CUBEVALUE(\"ThisWorkbookDataModel\",\"[Measures].[Sales]\")", "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/CUBEVALUE.html", "variants": [], "versions": [] }