{ "category": "Cubes", "display_name": "CUBESET", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.CUBESET", "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.CUBESET.json", "name": "CUBESET", "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`CUBESET` sits between the coordinate producers and the value consumer:\n\n- `CUBEMEMBER` is its scalar counterpart — one member instead of a set. The two are the\n family's constructors.\n- `CUBESETCOUNT` and `CUBERANKEDMEMBER` exist *only* to consume `CUBESET` results; neither has\n any other meaningful input.\n- `CUBEVALUE` accepts a `CUBESET` result as a `member_expression`, which is how a workbook gets\n a subtotal over an arbitrary member collection.\n\nOutside the family, the natural comparison is a PivotTable filter or a `FILTER` over a table:\nboth express \"the subset I care about\". The difference is that `CUBESET` pushes the definition\nto the server and keeps the members on the server, which is what makes it viable for\nmillion-member dimensions.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n- The result is a handle, not data. An implementation that materializes members into the cell,\n or spills them, is a different function — `CUBERANKEDMEMBER` would then have nothing to do.\n- Sort order is semantic, not cosmetic, because `CUBERANKEDMEMBER` indexes the sorted set.\n Getting sort stability wrong changes which member \"rank 1\" names, silently.\n- The three sort families (measure, alphabetic, natural) require three different server\n capabilities. Natural order in particular cannot be reconstructed client-side from captions —\n it is a property of the dimension definition.\n- The 255-character limit applies to the expression as passed, with cell references as the\n documented escape hatch. Any code generator emitting MDX must plan for that.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nOne cell, one set. Not a spilled array, and not usable directly in ordinary array formulas.\nEverything downstream goes through `CUBESETCOUNT`, `CUBERANKEDMEMBER`, or `CUBEVALUE`.\n\nWhile the request is outstanding the cell displays `#GETTING_DATA…` — an extended-family\ntransient placeholder, catalogued in [the value universe](../model/01-value-universe.md), not a\nfailure.\n\nAn empty result set is a state worth naming and one the Handbook cannot describe from\ndocumentation: a set expression that legitimately matches nothing is different from a set\nexpression that is malformed, and the documentation does not say which of the two outcomes an\nempty set produces. That question is listed 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`** — the `set_expression` syntax is incorrect; the set contains at least one member\n with a different dimension from the others; or the expression refers to a session-scoped\n calculated member or named set whose PivotTable has been deleted or converted to formulas.\n- **`#VALUE!`** — `set_expression` is longer than 255 characters.\n\nThe Handbook has not observed any of these against a live Excel build; they are documented\nbehaviour with the source named.\n\n\n", "sources": "- Microsoft, \"CUBESET function\" —\n \n (syntax, all five arguments, the complete `sort_order` table with its enumerated constants\n and `sort_by` requirements, the 255-versus-32,767 character rule, and every error condition\n listed above).\n- Handbook `data/presence/FUNC.CUBESET.json` — no implementation module, no dispatch 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": "\n`CUBESET` is the family's set constructor. It is also the one cube function that asks the\nserver to *do work and remember it*: Microsoft's description is that it \"defines a calculated\nset of members or tuples by sending a set expression to the cube on the server, which creates\nthe set, and then returns that set to Microsoft Excel.\"\n\n\n`CUBESET` evaluates an MDX set expression against the cube and returns a handle to the\nresulting set, held in one cell. What lands in the cell is not the members themselves — it does\nnot spill, and it is not an array. It is a single cell whose display value is a caption and\nwhose identity is the set, consumable by three other functions:\n\n- `CUBESETCOUNT` asks it how many items it holds,\n- `CUBERANKEDMEMBER` pulls out the nth item,\n- `CUBEVALUE` slices by the whole set at once, letting the cube aggregate across it.\n\nOptionally the server is also asked to **sort** the set before returning it, and the sort is\npart of the set's identity — `CUBERANKEDMEMBER` indexes into the sorted order. This is why\n`CUBESET`'s sort arguments matter far more than a presentation setting would: they determine\nwhat \"the top performer\" means.\n\nThe sort orders Microsoft documents:\n\n| Integer | Constant | Behaviour | `sort_by` |\n|---|---|---|---|\n| 0 | `SortNone` | leaves the set in existing order (the default) | ignored |\n| 1 | `SortAscending` | ascending by `sort_by` | required |\n| 2 | `SortDescending` | descending by `sort_by` | required |\n| 3 | `SortAlphaAscending` | alpha ascending | ignored |\n| 4 | `SortAlphaDescending` | alpha descending | ignored |\n| 5 | `SortNaturalAscending` | natural ascending | ignored |\n| 6 | `SortNaturalDescending` | natural descending | ignored |\n\nThree sort *families* hide in that table, and conflating them is the usual source of surprise.\nOrders 1 and 2 sort by a **measure** (`sort_by` names it). Orders 3 and 4 sort by **caption\ntext**. Orders 5 and 6 sort in the cube's **natural** order — the hierarchy's own declared\nmember order, which is what makes months come out January-first rather than April-first.\n\n\n\n### Arguments\n\n\n`CUBESET(connection, set_expression, [caption], [sort_order], [sort_by])`\n\n- **`connection`** (required) — text; the name of a connection stored in the workbook. A lookup\n key, not a connection string.\n- **`set_expression`** (required) — text holding an MDX set expression, *or* a reference to an\n Excel range containing members, tuples or sets. Microsoft documents a **255-character limit**\n on the expression, and states that a cell reference may instead carry up to 32,767\n characters. Generated MDX crosses 255 characters easily, so this asymmetry is a practical\n constraint on how such workbooks must be built, not a footnote.\n- **`caption`** (optional) — text displayed in the cell in place of the cube's caption.\n- **`sort_order`** (optional) — one of the integers above; default 0.\n- **`sort_by`** (optional) — text naming the value to sort by. **Required** when `sort_order`\n is 1 or 2, and ignored otherwise. This is the argument position most often gotten wrong: it\n is not a column, a member, or a cell reference to sorted data — it is a value expression the\n server evaluates per member.\n\n\n" }, "signature": { "display": "CUBESET(connection, set_expression, [caption], [sort_order], [sort_by])", "parameters": [ { "description": null, "name": "connection", "optional": false, "repeats": false }, { "description": null, "name": "set_expression", "optional": false, "repeats": false }, { "description": null, "name": "caption", "optional": true, "repeats": false }, { "description": null, "name": "sort_order", "optional": true, "repeats": false }, { "description": null, "name": "sort_by", "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": 5, "min": 2 }, "category": "Cubes", "classification": {}, "descriptions": { "long": null, "short": "A set of members or tuples computed by an OLAP cube server", "short_source": "dna-calc-own" }, "docs": { "english_description": "Defines a calculated set of members or tuples by sending a set expression to the cube on the server, which creates the set, and then returns that set to Microsoft Excel.", "microsoft_url": "https://support.microsoft.com/en-us/office/cubeset-function-5b2146bd-62d6-4d04-9d8f-670e993ee1d9" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "CUBESET" }, { "locale": "bg-BG", "name": "CUBESET" }, { "locale": "cs-CZ", "name": "CUBESET" }, { "locale": "da-DK", "name": "KUBESÆT" }, { "locale": "de-DE", "name": "CUBESET" }, { "locale": "el-GR", "name": "CUBESET" }, { "locale": "en-AU", "name": "CUBESET" }, { "locale": "en-GB", "name": "CUBESET" }, { "locale": "en-US", "name": "CUBESET" }, { "locale": "es-ES", "name": "CONJUNTOCUBO" }, { "locale": "et-EE", "name": "CUBESET" }, { "locale": "fi-FI", "name": "KUUTIOJOUKKO" }, { "locale": "fr-FR", "name": "JEUCUBE*" }, { "locale": "he-IL", "name": "CUBESET" }, { "locale": "hr-HR", "name": "CUBESET" }, { "locale": "hu-HU", "name": "KOCKA.HALM" }, { "locale": "id-ID", "name": "CUBESET" }, { "locale": "it-IT", "name": "CUBESET" }, { "locale": "ja-JP", "name": "CUBESET" }, { "locale": "ko-KR", "name": "CUBESET" }, { "locale": "lt-LT", "name": "CUBESET" }, { "locale": "lv-LV", "name": "CUBESET" }, { "locale": "nb-NO", "name": "CUBESET" }, { "locale": "nl-NL", "name": "KUBUSSET" }, { "locale": "pl-PL", "name": "ZESTAW.MODUŁÓW" }, { "locale": "pt-BR", "name": "CUBESET" }, { "locale": "pt-PT", "name": "CONJUNTOCUBO" }, { "locale": "ro-RO", "name": "CUBESET" }, { "locale": "ru-RU", "name": "КУБМНОЖ" }, { "locale": "sk-SK", "name": "CUBESET" }, { "locale": "sl-SI", "name": "CUBESET" }, { "locale": "sr-Latn-RS", "name": "CUBESET" }, { "locale": "sv-SE", "name": "KUBUPPSÄTTNING" }, { "locale": "th-TH", "name": "CUBESET" }, { "locale": "tr-TR", "name": "KÜPKÜMESİ işlevi" }, { "locale": "uk-UA", "name": "CUBESET" }, { "locale": "vi-VN", "name": "CUBESET" }, { "locale": "zh-CN", "name": "CUBESET" }, { "locale": "zh-HK", "name": "CUBESET" }, { "locale": "zh-TW", "name": "CUBESET" } ], "signature": { "display": "CUBESET(connection, set_expression, [caption], [sort_order], [sort_by])", "parameters": [ { "description": null, "name": "connection", "optional": false, "repeats": false }, { "description": null, "name": "set_expression", "optional": false, "repeats": false }, { "description": null, "name": "caption", "optional": true, "repeats": false }, { "description": null, "name": "sort_order", "optional": true, "repeats": false }, { "description": null, "name": "sort_by", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "CUBESET", "version_marker": null, "xlcall": { "code": "478", "symbol": "xlfCubeset" } }, "microsoft": "https://support.microsoft.com/en-us/office/cubeset-function-5b2146bd-62d6-4d04-9d8f-670e993ee1d9" }, "try_it": { "formula": "=CUBESET(\"ThisWorkbookDataModel\",\"[Product].[All Products].Children\")", "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/CUBESET.html", "variants": [], "versions": [] }