QlikElixir.QIX.App (qlik_elixir v0.3.5)

View Source

High-level API for interacting with Qlik apps via QIX Engine.

This module provides user-friendly wrappers around the low-level Session and Protocol modules, making it easy to extract data from Qlik visualizations.

API Reference

Features

  • Navigation: List sheets and visualization objects
  • Data Extraction: Get hypercube data from charts and tables
  • Streaming: Stream large datasets page by page
  • Selections: Filter data by making selections in fields
  • Expressions: Evaluate custom Qlik expressions

Quick Start

alias QlikElixir.QIX.{Session, App}

# Connect to an app
{:ok, session} = Session.connect("app-id", config: config)

# List sheets
{:ok, sheets} = App.list_sheets(session)

# Get objects on a sheet
{:ok, objects} = App.list_objects(session, sheet_id)

# Extract data from a visualization (the main event!)
{:ok, data} = App.get_hypercube_data(session, object_id)
# Returns: %{headers: [...], rows: [...], total_rows: N}

# Make selections to filter data
:ok = App.select_values(session, "Country", ["USA", "Germany"])

# Evaluate expressions
{:ok, total} = App.evaluate(session, "Sum(Sales)")

# Disconnect when done
:ok = Session.disconnect(session)

Data Format

get_hypercube_data/3 returns a structured result:

%{
  headers: ["Country", "Sales", "Margin"],
  rows: [
    %{text: ["USA", "$1.2M", "23%"], values: ["USA", 1200000, 0.23]},
    %{text: ["Germany", "$900K", "19%"], values: ["Germany", 900000, 0.19]}
  ],
  total_rows: 50,
  truncated: false
}

Summary

Types

hypercube_result()

Functions

clear_selections(session, opts \\ [])

Clears all selections in the app.

evaluate(session, expression, opts \\ [])

Evaluates a Qlik expression.

get_hypercube_data(session, object_id, opts \\ [])

Extracts hypercube data from a visualization.

get_layout(session, object_handle, opts \\ [])

Gets the layout of a visualization object.

get_object(session, object_id, opts \\ [])

Gets a visualization object by ID.

list_objects(session, sheet_id, opts \\ [])

Lists visualization objects on a sheet.

list_sheets(session, opts \\ [])

Lists all sheets in the connected app.

select_values(session, field_name, values, opts \\ [])

Selects values in a field.

stream_hypercube_data(session, object_id, opts \\ [])

Streams hypercube data for large datasets.

Types

hypercube_result()

@type hypercube_result() :: %{
  headers: [String.t()],
  rows: [%{text: [String.t()], values: [any()]}],
  total_rows: non_neg_integer(),
  truncated: boolean()
}

Functions

clear_selections(session, opts \\ [])

@spec clear_selections(
  pid(),
  keyword()
) :: :ok | {:error, QlikElixir.Error.t()}

Clears all selections in the app.

Examples

:ok = App.clear_selections(session)

evaluate(session, expression, opts \\ [])

@spec evaluate(pid(), String.t(), keyword()) ::
  {:ok, any()} | {:error, QlikElixir.Error.t()}

Evaluates a Qlik expression.

Examples

{:ok, 1234567.89} = App.evaluate(session, "Sum(Sales)")
{:ok, "Q1 2024"} = App.evaluate(session, "=Max(Quarter)")

get_hypercube_data(session, object_id, opts \\ [])

@spec get_hypercube_data(pid(), String.t(), keyword()) ::
  {:ok, hypercube_result() | list()} | {:error, QlikElixir.Error.t()}

Extracts hypercube data from a visualization.

This is the main function for getting data out of Qlik visualizations.

Options

  • :page_size - Number of rows per page (default: 1000)
  • :max_rows - Maximum total rows to fetch (default: 10000)
  • :path - HyperCube path in layout (default: "/qHyperCubeDef")
  • :format - Return format: :raw or :formatted (default: :formatted)

Examples

# Get formatted data with headers
{:ok, %{headers: ["Country", "Sales"], rows: [...]}} =
  App.get_hypercube_data(session, object_id)

# Get raw matrix data
{:ok, [[%{"qText" => "USA"}, ...]]} =
  App.get_hypercube_data(session, object_id, format: :raw)

get_layout(session, object_handle, opts \\ [])

@spec get_layout(pid(), non_neg_integer(), keyword()) ::
  {:ok, map()} | {:error, QlikElixir.Error.t()}

Gets the layout of a visualization object.

The layout contains hypercube definitions, dimension/measure info, etc.

Examples

{:ok, layout} = App.get_layout(session, object_handle)

get_object(session, object_id, opts \\ [])

@spec get_object(pid(), String.t(), keyword()) ::
  {:ok, non_neg_integer()} | {:error, QlikElixir.Error.t()}

Gets a visualization object by ID.

Returns the object handle that can be used for further operations.

Examples

{:ok, object_handle} = App.get_object(session, "chart-id")

list_objects(session, sheet_id, opts \\ [])

@spec list_objects(pid(), String.t(), keyword()) ::
  {:ok, [map()]} | {:error, QlikElixir.Error.t()}

Lists visualization objects on a sheet.

Examples

{:ok, objects} = App.list_objects(session, "sheet-id")
# Returns list of object info with qId, qType, etc.

list_sheets(session, opts \\ [])

@spec list_sheets(
  pid(),
  keyword()
) :: {:ok, [map()]} | {:error, QlikElixir.Error.t()}

Lists all sheets in the connected app.

Examples

{:ok, sheets} = App.list_sheets(session)
# Returns list of sheet objects with qInfo.qId, qMeta.title, etc.

select_values(session, field_name, values, opts \\ [])

@spec select_values(pid(), String.t(), [String.t()], keyword()) ::
  :ok | {:error, QlikElixir.Error.t()}

Selects values in a field.

Examples

:ok = App.select_values(session, "Country", ["USA", "Germany"])

stream_hypercube_data(session, object_id, opts \\ [])

@spec stream_hypercube_data(pid(), String.t(), keyword()) :: Enumerable.t()

Streams hypercube data for large datasets.

Returns a Stream that yields pages of data.

Options

  • :page_size - Number of rows per page (default: 1000)
  • :path - HyperCube path in layout (default: "/qHyperCubeDef")

Examples

App.stream_hypercube_data(session, object_id)
|> Stream.each(&process_page/1)
|> Stream.run()