useData

The hook for returning data for use in visualisations

Overview

The useData hook returns data from the engine for either KPIs or visualisations. For dimensions and measures to build charts, use the cols input and for expressions to build KPIs use the metrics input.

Basic Example

The below example returns data to the console for a number of Qlik dimensions and expressions.

  
 const cols = [{
      qField: "[OrderDateMonth]",
      qLabel: "Order Date",
    },
    {
      qField: "[Country",
      qLabel: "Body Location",
    },
    {
      qField: "=Sum(Price*Quantity)",
      qLabel: "price",
      qFillStyle: "orange",
    }]

  const {
    dataSet,
  } = useData({
    cols,
    qTitle,
  });

  console.log(dataSet)

// ...

KPI Example

See below for an example of how to get data from the engine to build a KPI. Here we are creating storing the output from two Qlik expressions into a variable called metrics. You can pass in expressions or variables to the hook.

 // .....
 
   const qMetrics = [{
    qName: "KPI 1",
    qExpr: "=$(vQuantity)",
    qType: "qStringExpression"
  },
  {
    qName: "KPI 2",
    qExpr: "=Sum(Price*Quantity)",
    qType: "qStringExpression"
  }]

  const {
    metrics,
  } = useData({
    qMetrics,
  });

  console.log('metric: ',metrics)
  
  //...

Master Items Example

If you are using Master Items from your Qlik Sense app, your cols config will be looking slightly different. See below for an example

import React from 'react'
import { useData } from '@motor-js/engine'

const MasterItemsExample = () => {

  const cols = [
  {
    qField: "[OrderDateMonth]",
    qLabel: "Order Date",
  },
  {
    qField: "",
    qLibraryId: "dWHamW",
    qType: "measure",
  }];
  
  const { dataSet, headerGroup } = useData({
    cols,
  });

 //....

Data Options

The following options can be passed into the hook

• cols: Array

  • Optional

  • The columns in your Qlik application you wish to extract data for

  • Can be an array of strings or an array of objects

  • See Cols Options for the object definition

• qPage: Object

  • Optional

  • Must be an object in the following structure: { qTop: num, qLeft: num, qWidth: num, qHeight: num }

  • Size of the extracted data from the engine

• qTitle: string

  • Title of your visualisation

• qSubtitle: string

  • Subtitle

• qMetrics: array<object>

  • An array of Metric objects

  • Expressions to calculate KPI values

  • See Metric Options for the object definition

Cols Options

• qField: <string> | <array>

  • Required

  • Dimension or Measure name from your Qlik Sense data model

  • Pass an array to use a drill down group

• qLibraryId: <string>

  • Use to refer to a Master Item created in your app

  • Must refer to the id of your Master Item

• qType: <"dimension" | "measure">

  • Use along with qLibraryId, if you are using Master Items from your Qlik Sense data model

  • Required to label your qLibraryId as a dimension or measure

• qLabel: <string>

  • Label of your dimension / measure. This will be available in the headerGroup object to use as your table's title

• qGrouping: <oneOf>

  • N or GRP_NX_NONE

  • H or GRP_NX_HIEARCHY

  • C or GRP_NX_COLLECTION

  • Use H for a drill down group

• qNumType: <oneOf>

  • U or UNKNOWN

  • A or ASCII

  • I or INTEGER

  • R or REAL

  • F or FIX

  • M or MONEY

  • D or DATE

  • T or TIME

  • TS or TIMESTAMP

  • IV or INTERVAL

  • To set the number type of the returned text

• qNumFmt: <string>

  • Format of number e.g. '$#,##0'

• qFillStyle: <string>

  • Fill colour of your measure to be used in your chart

Metric Options

• qName: string

  • Name of the metric

• qExpr: string

  • Qlik expression to calculate a single value

• qType: oneOf

  • qStringExpression

  • qValueExpression

  • Whether the expression should return a string or numeric value

Data Properties

The following properties are returned from the hook

• DataSet: Array

  • An array of data objects, contains the data returned from the engine

  • The structure of this object can change depending on your cols input

  • See Data Properties for more details

• DataKeys: Array

  • An array of data keys, contains the dimension names, which your measure is calculated across or the name of the measure. This depends on the number of dimensions and measures you are passing into cols.

  • See Data Keys Properties for more details

• DataList: Array

  • See Data List Properties for more details

• select: Function(column, [elemNumber], toggle)

  • A function to apply selections against the Qlik engine

  • You need to pass:

    • Column to apply selection against Needs to be an array of the element numbers you wish to select

    • An array of element numbers to select

    • Whether to toggle selections, optional parameter, default set to false

  • Element numbers are equivalent to the elemNumber in the dataKey object, in dataSet

• beginSelections: Function

  • A function to begin the selections mode, equivalent to this Qlik method

• endSelections: Function

  • A function to end the selections mode, equivalent to this Qlik method

• selections: Array

  • An array of selected element numbers

• clearSelections: Function

  • Clears all selections for the particular dimension

• metrics: Object

  • An object containing the output from Metric options (qMetrics array)

DataSet Properties

• qElemNumber: Number

  • Element number of the data point relating to the primary dimension

• label: String

  • Label of the data point

• [dimensionOneName]: String

  • Primary dimension values

• [dimensionTwoName]: String

  • Second dimension values. Will be present if two dimensions are passed into the cols object

• [dimensionTwoName]-qElemNumber: Number

  • Element number associated to each of the second dimension data points

  • Will be present if two dimensions are passed into the cols object

• [measureName]: String | Number

  • Measure value, will be present if only 1 dimension is passed into the cols object

• key: Number

  • Unique key for each object in the DataSet array

DataKey Properties

• [keyName]: string

  • Relates to a data point in each Data Object

  • Could be a measure name or list of dimension values depending on your cols definition

Data List Properties

Contains an array of dataKeyobjects. Please see Data Key Properties for more details