--- title: "BOARD.READ" slug: "board-read-excel-function" description: "Unlock faster data retrieval with BOARD.READ, using one formula to respect or ignore sheet selections in your Board Data Model or Cube." tags: ["Excel Add-In", "Excel", "BOARD.WRITE", "BOARD.READ", "BCUBE", "BSAVE", "Add-in"] updated: 2026-11-06T14:57:51Z published: 2026-11-06T14:57:51Z canonical: "help.board.com/board-read-excel-function" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.board.com/llms.txt > Use this file to discover all available pages before exploring further. # BOARD.READ The **BOARD.READ** function (previously **BCUBE** and **BCUBE_K** in the MS Office Add-in) retrieves data from a Board Data Model, Dataset, or Cube for a set of specified coordinates (named Entity members). The MS Office Add-in functions BCUBE and BCUBE_K were equivalent to each other with one single difference: the Selection criteria as specified in the Board Platform was either ignored or respected. The **BOARD.READ** function has a Boolean function to achieve the same difference in one function rather than two by adding the "Ignore sheet selection" parameter. The bulk refresh logic of BOARD.READ refreshes formulas in groups rather than individually, allowing a quicker execution. BOARD.READ recalculates upon refresh and also when contained by an Excel formula. > [!NOTE] > Excel formulas that do not contain a Board formula are recalculated according to Excel settings and logic. The Board refresh does not affect these formulas. Read more about [Board Refresh](/v15/docs/refresh-tables) in the M365 Excel Add-in. ### Key benefits of BOARD.READ - Retrieves data from specific set of coordinates in a Dataset or Cube - Now uses one formula instead of two - Faster execution than before, through grouped refresh operations [KB-B15 - Board M365 Excel Add-in BOARD.READ-1.mp4](https://cdn.document360.io/8d6f1ae8-0cac-4d0d-a208-6245b83df94a/Images/Documentation/KB-B15%20-%20Board%20M365%20Excel%20Add-in%20%20BOARD.READ-1.mp4) ## Writing BOARD.READ syntax The basic syntax of the **BOARD.READ** function is: ```excel =BOARD.READ("Data_Model","Cube_Name","Entity1=member_code1,member_code2;Entity2=member_code30:member_code40","Selection/ignore") ``` > [!NOTE] > Mandatory parameters are "Data_Model" and "Cube_Name". "Data_Model", "Cube_Name", and "Entity" names are NOT case sensitive.​ > > Coordinates and ignore sheet selection switch are optional. The full possible syntax for **BOARD.READ** is: ```excel =BOARD.READ("Data_Model","Cube_Name;Rule=Rule_name","Entity1=member_code1,member_code2;Entity2=member_code30:member_code40","Selection/ignore","Time_Function") ``` > [!NOTE] > The additional parameters in the syntax are Rules and Time Functions. ### Ignore or respect Selections The Ignore sheet selection parameter in the BOARD.READ formula controls whether the formula respects the current Sheet Selection. The two possible settings are: - **Ignore sheet selection=TRUE** When Selections are ignored, they are **not applied** when the BOARD.READ formula retrieves the data. This still allows users the freedom to specify the 'filtering' coordinates of the BOARD.READ formula to suit their current needs. - **Ignore sheet selection=FALSE** When Selections are respected, the BOARD.READ formula returns only data that matches the current Selection. This allows users to display data with another selection layer after respecting the Sheet Selection. > [!NOTE] > If the parameter is left blank, the default is "FALSE" and the BOARD.READ formula respects the Sheet Selection. > [!TIP] > Example > > The first formula sets the Sheet Selection to "Region=Europe". The second retrieves data for "Year=2020" and respects that selection: > > ```excel > =BOARD.SETSELECTION("Echo","Region=Europe", TRUE) > ``` > > ```excel > =BOARD.READ("Echo","Customer Demand","Year=2020", FALSE) > ``` > > The result of the second formula is data for Europe in 2020. If the BOARD.READ coordinates specified "Region=North America" instead, they would conflict with the active Sheet Selection and the formula would return "0". > > > > To ignore the active Sheet Selection, set the Ignore sheet selection parameter in BOARD.READ to "TRUE" and specify the coordinates you want the formula to use: > > ```excel > =BOARD.READ("Echo","Customer Demand","Year=2020";"Region=North America", TRUE) > ``` > [!NOTE] > For both ignored and respected selections, **security selections are always respected** and applied before any other selection. > [!NOTE] > ​Coordinates are matched with either Entity member codes or description. Users don't need to specify the codes, but do need to specify descriptions to retrieve the data.​ > > **Duplicate member description known limitation** If multiple members have the same description, Excel applies only the first member that occurs and ignores the rest. > > **Solution**: Define the member by their code an not by description. > [!NOTE] > Entity names, Cube names, Data Model names, and Entity elements containing the following reserved **characters ("=", ",", ":", ";") are not supported** with these Excel formulas.​ **Security is always applied** on the formulas, similarly to any other in-Platform Board Object. ​ **Cell references** can be used to make formulas dynamic, but the "&" character must be used to correctly to combine the different cells and obtain a parameter which is in line with the formula definitions.​ **If any errors occur** retrieving the data, the error will be displayed in Excel using the standard error tooltip that can be found in any Excel formula.​ > > If a **Cube has an unbalanced hierarchy**, the default keeps the unbalance hierarchy rollup without adding the string DISABLEUNBALANCED=false, but you can also use it to achieve the same outcome. ### Coordinates BOARD.READ uses the standard coordinate syntax and validation rules shared across Board Excel functions. For information about specifying coordinates, validation rules, supported syntax, and examples, see [Coordinate syntax and validation](/v15/docs/custom-board-m365-excel-functions#coordinate-syntax-and-validation). > [!NOTE] > The BOARD.SETSELECTION functions update the sheet selection criteria so they are recognized by BOARD.READ which retains and respects sheet Selections if parameter is set to "true". #### Using coordinates from parallel Entities In specific cases when a BOARD.READ formula contains **coordinates from two Entities that are parallel to the Cube dimension**, Board: - Aligns the coordinates to their nearest common less-aggregate Entity. - Evaluates the intersection of the coordinate member sets. **If the coordinates intersect**, BOARD.READ uses the intersecting members and aligns them to the Cube dimension. **If the coordinates do not intersect**, BOARD.READ returns `0` for a numerical Cube or an empty string for a text Cube. This behavior applies even if both coordinates relate to the same member of the Cube dimension. > [!TIP] > Examples > > If the first coordinate relates to members A1, A2 and the second relates to members A2, A3, **the coordinates intersect at A2**. **BOARD.READ uses A2** and aligns it to the Cube dimension. > > If the first coordinate relates to members A1, A2 and the second relates only to A3, **the coordinates do not intersect**. **BOARD.READ returns** `0` for a numerical Cube or an empty string for a text Cube. This behavior also applies when the formula contains coordinates from two less-aggregate Entities, or from one less-aggregate Entity and one parallel Entity. ### Optional strings and parameters #### Additional Cube strings: Rules and disable Unbalance hierarchy Cubes in BOARD.READ formulas can have extra parameters, applying a Rule or disabling the Unbalance hierarchy rollup. **To add a Rule and/or to disable the Unbalance hierarchy rollup**, add the following syntax in the "Cube_Name" section using ";" as separators: "*Cube_Name; RULE=Rule_Name;DISABLEUNBALANCED=true/false"* The full syntax with Rule looks as follows: ```excel =BOARD.READ("Data_Model","Cube_Name;RULE=Rule_Name;DISABLEUNBALANCED=true/false","Entity1=member_code1,member_code2;Entity2=member_code30:member_code40","Selection/ignore") ``` > [!NOTE] > If no parameter is set, the default is "FALSE" and and keeps the Unbalance hierarchy rollup. ### BOARD.READ Time Functions The "Functions" parameter of BOARD.READ is used to calculate totals or retrieve data from other periods based on certain time variables, as described in full detail in the [Time functions](/v15/docs/about-data-block-settings#time-functions) section of the Data Block settings. The "Functions" are optional parameters, separated from each other with semi-colons, that are used to evaluate the data queries. Add the Time function to the end of the syntax: ```excel =BOARD.READ("Data_Model","Cube_Name","Entity1=member_code1,member_code2;Entity2=member_code30:member_code40","Selection/ignore","Time_Function") ``` The following available time functions are the same as in the Layout Editor: - "pp" = previous period - "py"= previous year - "ycv" = yearly cumulated value - "ymt" = yearly moving total - "yma" = yearly moving average - "lastvalue" = last value - "fy" = fiscal year > [!NOTE] > "fy" can only be used in combination with "ycv", separated by a semicolon: e.g. "ycv;fy". - "cycle" = N (the number of periods to cumulate based on the Time Entity set By Row ) > [!NOTE] > "Cycle" considers the By Row Entity and not the Cube time dimension. For example, if Day dimensions a Cube and Quarter is set By Row, "cycle=3" cumulates the last 3 quarters. - "offset" = ±N (the number of earlier or later periods to offset based on the Time Entity for which the Cube is dimensioned) > [!NOTE] > "offset" can be used in combination with any other time function, separated by a semicolon from a following space and the mandatory offset value: e.g. "py;offset -1" > > The time selection is shifted by the specified number of periods. The number of periods may be negative for earlier periods, or positive for later periods. > [!NOTE] > Multiple Time Functions can be combined with the ";" separator. > [!TIP] > Examples > > To better clarify, here are some examples of some complex formulas and their intended results. Note that a combination of security restrictions, selections or the non-existence of the requested data mean that the formulas might not return any data at all. > > | py;offset 2 | Retrieve data values from 2 years ago for all periods. | > | --- | --- | > | pp;py;offset 2 | Retrieve data values from 2 years ago corresponding to the period prior to the current one. | > | ycv;offset 2;cycle 2;fy | Retrieve yearly cumulated values from the financial year that was 2 years ago, resetting to zero every 2 years. | > | yma;py;offset 5; cycle 1 | Retrieve yearly moving averages from the calendar year that was 5 years ago, resetting to zero every year. | > | ymt;cycle 3;py | Retrieve yearly moving totals from the current calendar, resetting to zero every 3 months. | ### BOARD.READ use cases The BOARD.READ formula gives you control over how data is pulled into your sheet, especially when combined with selection parameters. Use the BOARD.READ formula to fetch data—either with or without sheet selections. The difference hangs on a key parameter: whether the formula should respect the current sheet selection, or should it always show the value of the exact coordinate specified, regardless of the sheet selected. The video tutorial demonstrates the 3 different use cases, why the "ignore selection" parameter matters, and what changes when you adjust it. [Board.Read-use-case-examples.mp4](https://cdn.document360.io/8d6f1ae8-0cac-4d0d-a208-6245b83df94a/Images/Documentation/Board.Read-use-case-examples.mp4) All the formulas in this example call for values from Data Model "Demo_FR_SOP" and Cube "Customer Demand". The **three BOARD.READ use cases** are: 1. Calling data that **ignores the sheet selection**. The video shows 3 examples that ignores the sheet selection: 1. One with **only the required parameters**, Data Model and Cube, rendering the total value of that Cube without a sheet selection. ```excel =BOARD.READ("Demo_FR_SOP", "Customer Demand",,TRUE) ``` 2. The next with the **additional Coordinates parameter** set to Year 2020, displaying the total value of that Cube for the year 2020 only without a sheet selection. ```excel =BOARD.READ("Demo_FR_SOP", "Customer Demand","Year=2020",TRUE) ``` 3. The third with **multiple Coordinates** set to Year 2020 and Region North America, displaying the total value of that Cube for the year 2020 within the region of North America. ```excel =BOARD.READ("Demo_FR_SOP","Customer Demand","Year=2020;Region=NA",TRUE) ``` 2. Calling data that **respects the sheet selection**. The video shows a second set of 3 examples that respect the sheet selection. The first mimics the first formula in the aforementioned examples but with the ignore sheet selection parameter set to FALSE and therefore filtering the data of the formula according to the sheet selection which is Region Europe in the example. ```excel =BOARD.READ("Demo_FR_SOP","Customer Demand",,FALSE) ``` 3. Calling data with one or more **coordinates that also respects the sheet selection**. The data displayed is an **intersection of the two Selections**. The next 2 examples respecting the sheet selection call for one or more coordinates: 1. One selecting data by the coordinate Year 2020 like the aforementioned example, but also the sheet selection which is Region Europe in the example. ```excel =BOARD.READ("Demo_FR_SOP","Customer Demand","Year=2020",FALSE) ``` 2. The last one with the coordinates Year 2020 and Region North America like the aforementioned example, but displays 0 because the coordinates fall outside of the sheet selection Region Europe. ```excel =BOARD.READ("Demo_FR_SOP","Customer Demand","Year=2020;Region=NA",FALSE) ``` > [!NOTE] > If the coordinates of the formula are not coherent with the active selection (e.g. 2 conflicting filters applied to the same Entity), no data will be retrieved and the cell will display "0".