GetHyperCubeBinnedData method

Overview

This method supports data binning.

When a generic object with two or three measures and one dimension contains a lot of data, groups of points (i.e cells) can be rendered instead of points.

A zone of interest can be refined (for zooming in) up to a maximum refinement level (set in the qQueryLevel parameter) or coarsened (for zoom out).

The grid of cells is adaptive (not static), meaning that it adapts to different length scales.

The GetHyperCubeBinnedData method gives information about the adaptive grid and the values of the generic object.

The number of points in a cell and the coordinates (expressed in the measure range) of each cell are returned.

Dimension values and measure values are rendered at point level (highest detailed level).

The generic object should contain two or three measures and one dimension. When the refinement is high, the first two measures are represented on the x-axis and on the y-axis, while the third measure is visualized as color or point size.

Parameters

Name	Description	Type
qPath	Path to the definition of the object. For example, /qHyperCubeDef. This parameter is mandatory.	String
qPages	Array of pages to retrieve. Since the generic object contains two measures and one dimension, qWidth should be set to 3. If the value of a measure is Null, the value cannot be rendered. Therefore, the number of elements rendered in a page can be less than the number defined in the property qHeight. This parameter is mandatory.	Array of NxPage
qViewport	Defines the canvas and the zoom level. This parameter is not yet used and is optional.	NxViewPort
qDataRanges	Range of the data to render. This range applies to the measure values. The lowest and highest values of a measure can be retrieved by using the GetLayout method ( in /qHyperCube/qMeasureInfo). This parameter is mandatory.	Array of NxDataAreaPage
qMaxNbrCells	Maximum number of cells in the grid. This parameter is mandatory.	Integer
qQueryLevel	Level of details. The higher the level, the more detailed information you get (zoom-in). When the number of points to render falls below a certain threshold, the values are no longer rendered as cells but a s points. The query level should be no greater than 20. This parameter is optional.	Integer
qBinningMethod	Selects the algorithm. The default value is 0. One of: 0: Adaptive grid	Integer

Name	Description	Type
qLeft	Position from the left. Corresponds to the first column.	Integer
qTop	Position from the top. Corresponds to the first row.	Integer
qWidth	Number of columns in the page. The indexing of the columns may vary depending on whether the cells are expanded or not (parameter qAlwaysFullyExpanded in HyperCubeDef).	Integer
qHeight	Number of rows or elements in the page. The indexing of the rows may vary depending on whether the cells are expanded or not (parameter qAlwaysFullyExpanded in HyperCubeDef).	Integer

Name	Description	Type
qLeft	Position from the left. Corresponds to the lowest possible value of the first measure (the measure on the x-axis).	Double
qTop	Position from the top. Corresponds to the highest possible value of the second measure (the measure on the y-axis).	Double
qWidth	Width of the page. Corresponds to the highest possible value of the first measure (the measure on the x-axis).	Double
qHeight	Height of the page. The difference between qTop and qHeight gives the lowest possible value of the second measure (the measure on the y-axis).	Double

Outputs

A data set is returned.

Name	Description	Type
qDataPages	Information about the data set. Depending on the refinement level, the information is about: • The adaptive grid. Occurs when cells are rendered and not points. or • The dimension values and the measure values. Occurs when the level of details is high (points are rendered).	Array of NxDataPage

Name

Description

Type

qDataPages

Information about the data set.

Depending on the refinement level, the information is about:

• The adaptive grid. Occurs when cells are rendered and not points.

• The dimension values and the measure values. Occurs when the level of details is high (points are rendered).

Array of NxDataPage

Name	Description	Type
qMatrix	Array of data.	Array of NxCellRows
qTails	Array of tails. Is used for hypercube objects with multiple dimensions. It might happen that due to the window size some elements in a group cannot be displayed in the same page as the other elements of the group. Elements of a group of dimensions can be part of the previous or the next tail. If there is no tail, the array is empty [ ].	Array of NxGroupTail
qArea	Size and offset of the data in the matrix.	Rect
qIsReduced	Is set to true, if the data have been reduced. The default value is false.	Boolean

Name	Description	Type
NxCellRows	Array of data.	Array of NxCell

Name	Description	Type
qText	Some text. This parameter is optional.	String
qNum	A value. This parameter is optional.	Double precision floating point
qElemNumber	Rank number of the value, starting from 0. If the element number is a negative number, it means that the returned value is not an element number. You can get the following negative values: -1: the cell is a Total cell. It shows a total. -2: the cell is collapsed. Applies to pivot tables. -3: the cell belongs to the group Others. -4: the cell is empty. Applies to pivot tables.	Integer
qState	State of the value. The default state for a measure is L.	One of: L for Locked S for Selected O for Optional D for Deselected A for Alternative X for eXcluded XS for eXcluded Selected XL for eXcluded Locked
qIsEmpty	Is set to true, if qText and qNum are empty. This parameter is optional. The default value is false.	Boolean
qIsTotalCell	Is set to true if a total is displayed in the cell. This parameter is optional. The default value is false. Not applicable to list objects.	Boolean
qIsOtherCell	Is set to true if the cell belongs to the group Others. Dimension values can be set as Others depending on what has been defined in OtherTotalSpecProp. This parameter is optional. The default value is false. Not applicable to list objects.	Boolean
qFrequency	Frequency of the value. This parameter is optional.	String
qHighlightRanges	Search hits. The search hits are highlighted. This parameter is optional.	Null or NxHighlightRanges
qAttrExps	Attribute expression values.	Null or NxAttributeExpressionValues
qIsNull	Is set to true if the value is Null.	Boolean

Name	Description	Type
qRanges	Ranges of highlighted values	Array of CharRange

Name	Description	Type
qCharPos	Position of the first search occurrence	Integer
qCharCount	Number of occurrences found	Integer

Name	Description	Type
qValues	List of attribute expressions values.	Array of NxSimpleValue

Name	Description	Type
qText	Text related to the attribute expression value. This property is optional. No text is returned if the attribute expression value is a numeric.	String
qNum	Numeric value of the attribute expression. This property is set to NaN (Not a Number) if the attribute expression value is not a numeric. Numerical values are not returned as text.	Double precision floating point

Name

Description

Type

qText

Text related to the attribute expression value.

This property is optional. No text is returned if the attribute expression value is a numeric.

String

qNum

Numeric value of the attribute expression.

This property is set to NaN (Not a Number) if the attribute expression value is not a numeric.

Numerical values are not returned as text.

Double precision floating point

Name	Description	Type
qUp	Number of elements that are part of the previous tail. This number depends on the paging, more particularly it depends on the values defined in qTop and qHeight This parameter is optional. Is not shown if the value is 0.	Integer
qDown	Number of elements that are part of the next tail. This number depends on the paging, more particularly it depends on the values defined in qTop and qHeight This parameter is optional. Is not shown if the value is 0.	Integer

Name

Description

Type

qUp

Number of elements that are part of the previous tail.

This number depends on the paging, more particularly it depends on the values defined in qTop and qHeight

This parameter is optional. Is not shown if the value is 0.

Integer

qDown

Number of elements that are part of the next tail.

This number depends on the paging, more particularly it depends on the values defined in qTop and qHeight

This parameter is optional. Is not shown if the value is 0.

Integer

Name	Description	Type
qLeft	Position from the left. Corresponds to the first column.	Integer
qTop	Position from the top. Corresponds to the first row.	Integer
qWidth	Number of columns in the page. The indexing of the columns may vary depending on whether the cells are expanded or not (parameter qAlwaysFullyExpanded in HyperCubeDef).	Integer
qHeight	Number of rows or elements in the page. The indexing of the rows may vary depending on whether the cells are expanded or not (parameter qAlwaysFullyExpanded in HyperCubeDef).	Integer

Adaptive Grid

More details about the properties of the adaptive grid are given in this paragraph.

When the refinement is not the highest (cells are rendered), information about the adaptive grid is returned through several arrays.

The first array contains the following properties:

Name	Description	Type
qNum	Maximum number of points that a cell can contain.	String
qElemNumber	Is set to 0.	Boolean
qState	The default value is L.	One of: L for Locked S for Selected O for Optional D for Deselected A for Alternative X for eXcluded XS for eXcluded Selected XL for eXcluded Locked

Name

Description

Type

qNum

Maximum number of points that a cell can contain.

String

qElemNumber

Is set to 0.

Boolean

qState

The default value is L.

One of:

L for Locked
S for Selected
O for Optional
D for Deselected
A for Alternative
X for eXcluded
XS for eXcluded Selected
XL for eXcluded Locked

The next arrays give the coordinates of each cell in the page.

Each array contains the following properties:

Name	Description	Type
qText	Coordinates of a cell in the measure range. “qText”: “[[<left>, <top>, <right>, <bottom>], [<left>, <top>, <right>, <bottom>], .... [<left>, <top>, <right>, <bottom>]] Where: <left>, <top>, <right> and <bottom> are the coordinates of the cell in the measure range.	String
qNum	Number of points in the cell.	Double precision floating point
qElemNumber	Unique identifier for each cell, calculated by the engine during the construction of the grid. This element number is not stored in the database and can have a positive or a negative value.	Integer
qState	The default value is L.	One of: L for Locked S for Selected O for Optional D for Deselected A for Alternative X for eXcluded XS for eXcluded Selected XL for eXcluded Locked

Cells are represented as rectangles.

Dimension values and measures values

More details about the properties, when dimension and measure values are returned, are given in this paragraph.

When the refinement is high, points are rendered (not cells) and dimension and measure values for each cell are returned.

The first array is empty because no information on the adaptive grid is needed.

The next arrays bring information about the dimension and the measure values.

Name	Description	Type
qText	Text value of the dimension or the measure.	String
qNum	Numerical value of the dimension or the measure. Is set to 0 if the value is only text.	Double precision floating point
qElemNumber	Unique identifier for each cell, calculated by the engine during the construction of the grid. This element number is not stored in the database and can have a positive or a negative value.	Integer
qState	The default value is L.	One of: L for Locked S for Selected O for Optional D for Deselected A for Alternative X for eXcluded XS for eXcluded Selected XL for eXcluded Locked

Learn more

Get the adaptive grid and the values of a generic object

Did this page help you?

If you find any issues with this page or its content – a typo, a missing step, or a technical error – let us know how we can improve!

Leave your feedback here