Концепт Hypercube для Qlik Sense Developers

HyperCube

HyperCube можно считать сердцем большинства визуализаций. Это определение cube, предоставляемое Qlik Data Engine, которое содержит всю информацию о том, какие данные запрашиваются и как они рассчитываются. Если выборка (selections) применяется к HyperCube, отображаются только выбранные значения.

HyperCube можно визуально представить как обычную прямую таблицу в Qlik с набором измерений и метрик, а также с дополнительными атрибутами.

Объект qHyperCubeDef играет значительную роль в создании визуализаций и других компонентов, которые в значительной степени зависят от механизма Qlik engine для расчетов.

qHyperCubeDef

qHyperCubeDef– это описание объекта, который передается в API Qlik Engine для создания запроса для обработки. Большинство визуализаций, встроенных в Qlik Sense, основаны на определении HyperCube на корневом уровне (root level), то есть код расширения (extension) построен на этой технологии.

Фундаментальное определение HyperCube (гиперкуба) выглядит следующим образом:

initialProperties:{
    version:1.0,
    qHyperCubeDef:{
    qDimensions:[],
    qMeasures:[],
    qInitialDataFetch:[{
        qWidth:2,
        qHeight:50
}]
  }
}

По-умолчанию, большинство расширений (extensions) не будут иметь никаких измерений или мер, определенных в их первоначальных свойствах (initialProperties), чтобы позволить пользователю достичь того же самого путем добавления измерений и метрики через панель свойств.

Всегда добавляйте initialProperties, чтобы определить, сколько строк / столбцов доступно в вашем объекте JavaScript. При изменении начальных свойств initialProperties удалите и повторно добавьте расширение визуализации (visualization extension); простого обновления страницы (F5) будет недостаточно.

Размер фактического HyperCube в Qlik Engine определяется числом результирующих строк после его вычисления. Иногда HyperCube может быть огромным, и поэтому qInitialDataFetch позволяет вам определить, сколько из этих ячеек данных будет возвращено в код расширения. Это задается через параметры с qWidth и qHeight.

Произведение параметров qWidth*qHeight никогда не может превышать 10000 ячеек данных. Если вам необходимо вернуть более 10 000 ячеек данных для конкретного варианта использования или визуализации, вам потребуется реализовать последующую нумерацию (subsequent pagination) страниц в своем коде.

qHyperCubeDef properties – свойства

Существует несколько высокоуровневых свойств, которые могут помочь изменить и установить базовый HyperCube, даже за пределами измерений и мер.

qDimensions

qDimensions определяет массив измерений, которые будут использоваться в HyperCube. Обычно qDimensions определяется с помощью панели свойств, но это также может быть сделано вручную непосредственно в файле JSON. Последнее рекомендуется только для использования в мэшапах (mashup), когда вы определяете визуализацию на лету.

В дополнение к имени измерения (dimension name), Вы также можете определить параметры, такие как:

• qNullSuppression – подавляет нулевые значения в измерении
• qShowAll – если задано значение true, отображает все значения измерений, независимо от того, выбраны ли они
• qCalcCond – устанавливает условие вычисления, которое должно быть выполнено для вычисления измерения
• qTotalLabel и qOtherLabel перемаркировка (переименовывание) меток Other и Total в возвращенном HyperCube

Если вы используете панель свойств (property panel) для определения измерений, простое использование этих свойств в качестве ссылочных значений позволяет вам определять их напрямую, например:

suppressNulls:{
    type:"boolean",
    ref:"qNullSuppression",
    label:"Suppress Nulls",
    defaultValue: false
},

qMeasures

qMeasures очень похож на qDimensions, но помогает вам определить меры. Как и в случае с измерениями, они обычно задаются через панель свойств (property panel).

qInitialDataFetch

qInitialDataFetch помогает определить, сколько ячеек данных первоначально извлекается из вычисленного HyperCube.

qStateName

qStateName помогает определить имя альтернативного состояния, при этом $ (текущий выбор) является значением по умолчанию. Альтернативные состояния помогают создать виртуальный образ выборок, основанных на том же наборе данных, но не затронутых выборками, сделанными в других состояниях. В основном используется для сравнительного анализа.

qInterColumnSortOrder

Свойство qInterColumnSortOrder помогает определить порядок сортировки по столбцам в HyperCube. Он определяется с помощью массива целых чисел, например, [1,3,2,0], который указывает, в каком порядке будут сортироваться столбцы.

qSuppressZero

qSuppressZero удаляет строки с нулевыми значениями во всей строке HyperCube, если установлено значение true.

qSuppressMissing

qSuppressMissing удаляет строки, в которых отсутствуют значения по всей строке HyperCube, если установлено значение true.

qMode

qMode определяет, в какой структуре будет возвращен HyperCube. По умолчанию и для большинства соответствующих случаев использования режим данных возвращается в виде таблицы. Дополнительные расширенные режимы доступны следующим образом:

Pivot Table representation – Представление сводной таблицы (qMode P)

Stacked Table representation – Представление Стековая таблица (qMode K)

Tree representation – Представление дерева (qMode T)

Эти различные типы представлений являются расширенными и возвращают Вам предварительно агрегированный формат базовых измерений и мер, включая промежуточные итоги.

qNoOfLeftDims

Это свойство применяется к сводным таблицам и сложенным сводным таблицам.

В структуре сводной таблицы этот параметр используется, чтобы помочь определить, сколько и какие измерения заданы в виде строк, а какие повернуты по горизонтали (отображаются в столбцах). Это относительно продвинутый вариант, и дополнительную документацию по этому вопросу можно найти на странице справки Qlik Sense.

qAlwaysFullyExpanded

Это свойство применяется к сводным таблицам и сложенным сводным таблицам.

Это свойство гарантирует, что ячейки всегда раскрыты (Fully Expanded), если установлено значение true.

qMaxStackedCells

В сложенном режиме/в режиме с накоплением (qMode = K), этот параметр определяет максимальное количество ячеек для начальной выборки данных (по умолчанию 5000).

qPopulateMissing

Пропущенные значения или нули возвращаются как дефисы (-) в модели данных. qPopulateMissing заменяет числовые нули на 0, а строковые нули – пустыми строками. 

qShowTotalsAbove

Если true, он возвращает итоговую строку в первой строке гиперкуба. Их также можно получить from qHyperCube.qGrandTotalRow[i].qNum.

qIndentMode

Это свойство применяется к сводным таблицам и сложенным сводным таблицам.

Это свойство применяет отступ для сводных таблиц и позволяет изменять макет таблицы (layout), добавляя отступ в начало каждой строки.

qCalcCond

qCalcCond определяет условие вычисления для всего гиперкуба для вычисления. Это особенно полезно, когда у вас широкие таблицы с очень сложными вычислениями, и вы хотите убедиться, что пользователь отфильтровал подмножество данных перед запуском вычисления в движок Qlik. Тяжелые вычисления не только увеличивают время расчета, но и увеличивают использование RAM на вашем сервере Qlik Sense.

qSortbyYValue

Это свойство применяется к сводным таблицам и сложенным сводным таблицам.

qSortbyYValue включает сортировку по возрастанию или убыванию в значениях меры.

Возращаемая структура qHyperCube structure

Как только qHyperCubeDef определен с помощью набора свойств или с помощью панели свойств, Qlik Engine рассчитывает HyperCube при каждой выборке и взаимодействии с Qlik engine. После расчета он возвращает структуру qHyperCube в layout вместе с результатами.

В расширении (extension) MasteringQS следующий пример иллюстрирует возвращенный вычисленный qHyperCube для образца измерения и метрики:

Теперь Вы, наверное, можете интуитивно распознать большинство  объектов и переменных. Любое свойство, начинающееся с буквы q, является свойством определения Qlik; однако есть некоторые дополнительные, которые не имеют префикса (например, заголовок и подзаголовок).

Кроме того, вместе с qHyperCube, layout также возвращает информацию, хранящуюся в файле.qext которую можно получить через свойство объекта extensionMeta. То же самое относится к пользовательским свойствам, определенным в файле properties.js, которые также возвращаются в layout ,вместе с qHyperCube, например fontSize,fontFamily, и так далее.

Для начала обратите внимание на следующие объекты:

Из этих трех наиболее актуальным является, конечно, qDataPages, который содержит рассчитанные данные:

Если вы развернете узел qDataPages, то вы увидите следующее you:

В свою очередь каждая ячейка содержит следующую информацию:

Одной из типичных задач является преобразование данных qDataPages.qMatrix в массив объектов другого формата для лучшей обработки в коде расширения.

Например, если вы знаете, что у вас всегда будет только одно значение измерения и одна метрика, преобразование структуры данных в нечто более удобное для вашего кода может быть выполнено с помощью функции .map(), которая выглядит следующим образом:

var data = [];
 data = scope.layout.qHyperCube.qDataPages[0].qMatrix.map(function(d) {
 return {
     dimensionvalue: d[0].qText,
     measurevalue: d[1].qNum
 };
 })

Результат выглядит намного дружелюбнее:

qListObjectDef

The family of generic objects has provided qHyperCube with a sister called the qListObject. Unlike a HyperCube, a list object better serves the purposes of displaying one single dimension without any required calculation, meaning no metrics are required to be defined. As such, it is fairly straightforward to work the list objects, and their definition is very similar to the qHyperCube object, with some added extra properties but without measures. 

The following code is an example of creating a qListObjectDef and writing the resulting list object into the console:

//DefineListObject
var obj = {
    "qDef": {
    "qFieldDefs": ["Case Owner"]
    },
    "qShowAlternatives" : true,
    "qInitialDataFetch": [{
        qTop : 0,
        qLeft : 0,
        qHeight : 10000,
        qWidth : 1
    }]
    };

var app = qlik.currApp(this);

//Create the listbox as a session object which will persist over the //session and then be deleted.
app.createList(obj,function(listobject) {
  console.log(listobject)
})

Код возвращает следующий результат:

Это структура, очень похожая на qHyperCube, с ее qDataPages, но с дополнительной информацией о найденном объекте измерения и списка.

Помимо классических свойств, уже описанных для qHyperCube, для объекта qListObject вы можете определить следующие параметры:

qStringExpression и qValueExpression

Для простоты одноразовых вычислений, в которых вы просто хотите использовать всю мощь механизма Qlik Sense Engine, qStringExpression и qValueExpression являются младшими сестрами qHyperCube и qListObject. Они работают, используя ту же концепцию, что и остальные, но на более простом уровне: все, что вам нужно сделать, это определить выражение Qlik, и механизм вернет вам свой результат:

var app = qlik.currApp(this);
app.createGenericObject({
    user: {
qStringExpression:"=OSUser()"
    }, 
    version: {
qStringExpression:"=EngineVersion()"
    }, 
    fields: { 
qValueExpression:"=Count (DISTINCT $Field)"
    } 
}, function ( reply ) { 
    var str = "Version:" + reply.version + 
        str+= " Number of Fields:"+reply.fields; 
    if(reply.user) { 
        str += " User:" + reply.user; 
    }
    console.log(str)
}

Использование этих определений объектов очень удобно в сочетании с другими объектами, такими как qHyperCube.

Знак = в строковом выражении не является обязательным. Даже если знак = не указан, выражение вычисляется. Строковое выражение не оценивается, если выражение окружено чистыми кавычками.

Kill the hypercubes

Find the code shown in this video for both the Visualization API and the Capabilities API: https://github.com/ChristofSchwarz/qs-mash-KillHypercube

Mash-Up APIs Part 4: Creating Hypercubes

Qlik Sense Tutorial | Creating Qlik Sense Mashup by using Hypercube

Mash-Up APIs Part 3: Connecting to Fields

Getting started building mashup – Qlik Sense