Using visualization components and the query property to render a simple visualization

Using the query property of the Query visualization component is the simplest way to render an embeddable visualization with Looker visualization components. Using the query property (as opposed to the dashboard property) offers the following benefits:

  • You simply need to build a query in Looker; you do not need to create a dashboard.
  • The values that query accepts (Query.client_id or the query ID) are immutable; unless the underlying model changes, no changes to the Looker instance will affect the embedded visualization.

If you would like to create an embeddable visualization that responds to changes within the Looker UI, and therefore can be updated by Looker users other than app developers, follow the instructions on the Using visualization components and a dashboard ID to render a simple visualization documentation page.

To render an embeddable visualization by using Looker visualization components and the query property, make sure your setup meets the requirements, and then perform the following steps:

  1. Build a query in an Explore and copy the Query.client_id value.
  2. Embed the query into a React application.
  3. Add the Visualization component.
  4. Customize settings with the config property.

Requirements

Before you start, a few elements are needed:

  • You must have access to a Looker instance.
  • Whether you're building in the extension framework or your own stand-alone React application, it is important to authenticate with Looker's API and have access to the Looker SDK object. Read about Looker API authentication or our extension framework for more information.
  • Make sure you have installed the Looker Visualization Components NPM package and the @looker/components-data NPM package. Information on installing and using the visualization components package can be found in the README document, available in GitHub and NPM.

Step 1: Build a query in an Explore and copy the Query.client_id value

Use an Explore to build a query within the Looker UI. Add a supported visualization to the Explore and, optionally, configure its settings in the visualization's Settings menu.

Find the qid URL property in the browser's address bar. The alphanumeric value assigned to that property is the Query.client_id.

For example, if the URL is https://example.looker.com/explore/thelook/orders?qid=evomfl66xHx1jZk2Hzvv1R&toggle=fil,vis,vse, then the Query.client_id is evomfl66xHx1jZk2Hzvv1R.

The Query.client_id is a unique string that represents the query and the visualization settings. If you change anything in the query or the settings, the Query.client_id will change.

Copy the Query.client_id to use in the following step.

Step 2: Embed the query into a React application

Now you can take the Query.client_id and embed it into a React application.

Below is code for a hypothetical React application. This example was built in the Looker extension framework, and the Looker SDK object has been pulled in from the extension context provider.

import React, { useContext } from 'react'
import { ExtensionContext } from '@looker/extension-sdk-react'

export const MyReactApp = () => {
  const { core40SDK } = useContext(ExtensionContext)

  return null
}

To begin, we will make use of the DataProvider and Query components. DataProvider stores the SDK reference in context, and Query dispatches our network requests and formats the response rendering.

Additionally, you must provide two things:

  • An SDK object. The SDK object is pulled in from the extension context.
  • The Query.client_id. The Query.client_id is assigned to the query property.
import React, { useContext } from 'react'
import { ExtensionContext } from '@looker/extension-sdk-react'
import { DataProvider } from '@looker/components-data'
import { Query } from '@looker/visualizations'

export const MyReactApp = () => {
  const { core40SDK } = useContext(ExtensionContext)

  return (
    {/* pass the sdk object to DataProvider */}
    <DataProvider sdk={core40SDK}>
      {/* the value referenced by the `query` prop is
          unique to your looker instance. */}
      <Query query="evomfl66xHx1jZk2Hzvv1R"></Query>
    </DataProvider>
  )
}

Step 3: Add the Visualization component

Next add the Visualization component, which interprets the data and configuration settings that are returned by Query to render the expected chart.

import React, { useContext } from 'react'
import { ExtensionContext } from '@looker/extension-sdk-react'
import { DataProvider } from '@looker/components-data'
import { Query, Visualization } from '@looker/visualizations'

export const MyReactApp = () => {
  const { core40SDK } = useContext(ExtensionContext)

  return (
    <DataProvider sdk={core40SDK}>
      <Query query="evomfl66xHx1jZk2Hzvv1R">
        <Visualization />
      </Query>
    </DataProvider>
  )
}

This step outputs a visualization that looks like the following example:

A line graph visualization.

Step 4: Customize settings with the config property

Use the config property of the Query component to override visualization settings that are returned from the SDK. This property can alter any supported feature, from the type of visualization to the details of how each data series is rendered.

In the sample code below, the config property changes the chart type to sparkline and assigns a new color to the data series.

import React, { useContext } from 'react'
import { ExtensionContext } from '@looker/extension-sdk-react'
import { DataProvider } from '@looker/components-data'
import { Query, Visualization } from '@looker/visualizations'

export const MyReactApp = () => {
  const { core40SDK } = useContext(ExtensionContext)

  return (
    <DataProvider sdk={core40SDK}>
      <Query
        query={'evomfl66xHx1jZk2Hzvv1R'}
        config={{
          type: 'sparkline',
          series: [{ color: '#F4B400' }],
        }}
      >
        <Visualization />
      </Query>
    </DataProvider>
  )
}

The previous step renders this orange sparkline:

A sparkline visualization.

For a full list of the sub-properties that are available in the config property, visit the Visualization and Query property tables reference documentation.

Next steps