Embed Looker with Conversational Analytics

1. Before you begin

This codelab will guide you through integrating an embedded Looker dashboard with Conversational Analytics powered chat to create a unified natural language driven data experience. To get the most value, you should be familiar with Looker embedding, Conversational Analytics, JavaScript, and React.

What you'll learn

After following this codelab, you'll have learned:

• How to set up the Looker Embed Reference application locally
• How to build a chat React component with the Looker Components library
• How to send your embedded's dashboard's filter as context to Conversational Analytics
• How to enable your Conversational Analytic powered chat to control your embedded dashboard's filters

What you'll need

To complete this codelab, you'll need:

• A Looker instance with the ASC Demographic Data Looker Block installed and SSO embedding enabled
• API and developer access to your Looker instance
• A local environment with Node v18, yarn, Git, and gcloud installed
• A cloud project with these IAM roles set up for your user account:
• roles/bigquery.dataViewer BigQuery Data Viewer
• roles/bigquery.user BigQuery User
• roles/looker.instanceUser Looker Instance User

2. Set up Conversational Analytics

Let's set up the Conversational Analytics data agent your embedded dashboard's chat will use to answer natural language questions.

Auth with gcloud

1. Authenticate with your user account in your local environment:

gcloud auth login

2. Set application default credentials (ADC) and the billing project on your gcloud:

gcloud auth application-default login
gcloud auth application-default set-quota-project YOUR_PROJECT_ID

Enable Conversational Analytics APIs

3. Enable Cloud project APIs. Please replace YOUR_PROJECT_ID with the ID of your Google Cloud project:

gcloud services enable geminidataanalytics.googleapis.com bigquery.googleapis.com cloudaicompanion.googleapis.com --project=YOUR_PROJECT_ID

Create the data agent

4. Open Google Colab.
5. Inside Google Colab, load this notebook from the Looker Embed Reference repository.
6. Run all of the notebook steps. You will need your Cloud project ID and your Looker instance's URI with a trailing slash, like "https://my.looker.app/". You should have a successful result at the end of the notebook.

You now have a Conversational Analytics data agent available and ready to accept chat messages, query the Looker explores in your embedded Looker dashboard, and return results and visualizations.

3. Set up Looker Embed Reference

Let's set up the Looker Embed Reference application in your local environment so you can try out the example of integrating Conversational Analytics chat with an embedded Looker dashboard.

Clone the repository

1. Clone the github repo into your local environment. See the following example command below:

git clone "https://github.com/looker-open-source/LookerEmbedReference.git"

2. Navigate into the LookerEmbedReference directory you've cloned:

cd LookerEmbedReference

Set up and run the local frontend server

3. Install the dependencies in the Frontend directory

cd Frontend
yarn install

4. Set up an .env file in the Frontend directory root with credentials. YOUR_LOOKER_INSTANCE_URI should be your Looker instance's URI with no trailing slash. The file contents should be as follows:

PBL_CLIENT_PORT=3001 
API_HOST=http://localhost:3000
LOOKER_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKER_API_HOST=YOUR_LOOKER_INSTANCE_URI:19999
LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI

You can use the following example command to create the file:

cat > .env <<'EOF'
PBL_CLIENT_PORT=3001 
API_HOST=http://localhost:3000
LOOKER_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKER_API_HOST=YOUR_LOOKER_INSTANCE_URI:19999
LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
EOF

5. Run the frontend dev server:

yarn run dev

Set up and run the backend server locally

6. Open a new shell, terminal, console, or tab. Navigate into the Backend-Node directory and install the dependencies. Make sure to keep the previous shell/terminal with the frontend server running.

cd ../Backend-Node
yarn install

7. Set up a .env file in the Backend-Node directory root with credentials:

• YOUR_LOOKER_CLIENT_ID is your Looker client ID.
• YOUR_LOOKER_CLIENT_SECRET is your Looker client secret.
• YOUR_LOOKER_EMBED_SECRET is your embed secret.
• YOUR_PROJECT_ID is your Cloud project ID.
• YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH is your Looker instance URI with a trailing slash.
• YOUR_LOOKER_INSTANCE_URI is your Looker instance URI with no trailing slash.

The file contents should be as follows:

PBL_BACKEND_PORT=3000
LOOKERSDK_API_VERSION=4.0
LOOKERSDK_BASE_URL=YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH
LOOKERSDK_CLIENT_ID=YOUR_LOOKER_CLIENT_ID
LOOKERSDK_CLIENT_SECRET=YOUR_LOOKER_CLIENT_SECRET

LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKERSDK_EMBED_SECRET=YOUR_LOOKER_EMBED_SECRET

CLOUD_AGENT_ID=looker_embed_reference_data_agent
CLOUD_PROJECT_ID=YOUR_PROJECT_ID

You can use the following example command to create the file. Replace all credentials accordingly:

cat > .env <<'EOF'
PBL_BACKEND_PORT=3000
LOOKERSDK_API_VERSION=4.0
LOOKERSDK_BASE_URL=YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH
LOOKERSDK_CLIENT_ID=YOUR_LOOKER_CLIENT_ID
LOOKERSDK_CLIENT_SECRET=YOUR_LOOKER_CLIENT_SECRET

LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKERSDK_EMBED_SECRET=YOUR_LOOKER_EMBED_SECRET

CLOUD_AGENT_ID=looker_embed_reference_data_agent
CLOUD_PROJECT_ID=YOUR_PROJECT_ID
EOF

8. Run the backend dev server:

yarn run dev

You now have the front dev server running, serving the JavaScript for the web application. You also have the backend dev server running to take care of SSO Embed URL requests and proxy requests to the Conversational Analytics endpoints.

4. Try out the example

Let's try out your web application now running locally in your environment.

Start a conversation

1. Open the address https://localhost:3001 in your browser of choice.
2. Navigate to the Embedded Dashboard with Chat page in the left main navigation.
3. Once the chat component on the right loads, type in: "Hello, who are you?"
4. Note the response.

The application automatically created a Conversational Analytics conversation object to track chat history and loaded the chat interface. When you asked the chat interface a question, the frontend sent a user message to your local Node backend server. It then proxied the request to and the response from the Conversational Analytics chat endpoint.

Filter the embedded dashboard

Now familiarize yourself with the embedded dashboard and interact with it.

5. Scroll through the embedded dashboard. Note it covers census data across multiple dimensions and metrics.
6. You can filter the dashboard on State and County in the top left of the dashboard. Set the filter on the dashboard filter to Texas. Then select the newly blue highlighted circular arrow button to re-run the dashboard.
7. Note how all the visualizations data are filtered on the state Texas.

Ask a question with dashboard context

Now that we've filtered the dashboard, let's continue investigating the data in the dashboard.

8. Submit "Tell me the top 5 counties with lowest rent." in the chat.
9. Note, your prompt to Conversational Analytics now contains additional words "Filter on dimension ‘state.state_name' being Texas."
10. Now, note the response's query and data are filtered on the state Texas.
11. Also, after the data results were returned, your embedded dashboard has been re-run with its County filter set to the 5 counties defined in the result's data.

You can now continue investigating the census data, with the 5 counties filtered conveniently for you.

Congratulations! You've set up and tried out a simple example of an embedded dashboard integrated with a Conversational Analytics chat.

5. Build a chat component

Let's understand what's going on under the hood, by first exploring the Chat component. We assume you understand how to embed a Looker dashboard with the Looker Embed SDK.

Use the Looker Component library

1. Open the Chat component file at Frontend/src/components/EmbedChat/components/chat.js in your favorite IDE or in your terminal.
2. The Chat component is built with standard Looker UI React components from the Looker Components Library package.

The Looker Components Library enables seamless integration between Looker content and your application by providing pre-made React components that align with the styles and components in an embedded Looker dashboard.

Send a user message

The chat interface needs to send a user's prompt to Conversational Analytics.

3. Near the bottom of the Chat component file, the Chat component contains the ChatInput subcomponent, which provides the input field for a user's prompt.
4. On submit, the showAndSendUserPrompt method sends the user's prompt to Conversational Analytics (proxied through your Node backend).

Stream and display system messages

After the user has messaged Conversational Analytics, we need to display its response.

5. Near the bottom of the Chat component file, the Chat component contains the MessageList subcomponent, which contains the logic to display the messages from Conversational Analytics based on the message's type.
6. The streamAndParseResponse method handles the response, by constantly trying to parse valid system messages from the streaming JSON response. Whenever a valid system message has been successfully parsed, it is displayed in the MessageList.

We highly recommend you display the system messages from Conversational Analytics as soon as they arrive for a more responsive user experience.

Conversational Analytic's response to a user prompt consists of multiple system messages, covering the data source(s) queried, query, results, visualizations, and more. Waiting for all system messages to arrive can lead the user to assume performance or application issues.

You've now explored how the Chat component, built with the Looker Components library, sends a user message and streams back the response.

6. Send dashboard filters to Conversational Analytics

Now let's understand how to include the dashboard filters in a user's prompt so that Conversational Analytics can filter its query with the dashboard's context (its filters).

Listen to the dashboard's filter change event

1. Open the EmbedChat component file at Frontend/src/components/EmbedChat/EmbedChat.js, which represents the application's page containing the embedded dashboard integrated with the previously explored Chat component.
2. The EmbedChat component listens to the "dashboard:filters:changed" event from the embedded dashboard with Embed SDK's .on(...) method. Then the component stores the current filters in its filter state.

Send filter state to Conversational Analytics

3. The EmbedChat component passes the filters into the Chat component, which converts each filter into a string like "Filter on dimension '...' being ..." in the showAndSendUserPrompt method to be suffixed to the user's prompt.

A dashboard's filter's name or key is not necessarily the same as the actual dimension's name. You must map the filter's key to the actual dimension's name so Conversational Analytics understands what dimensions to filter on.

In this case, for example in the Chat component, its FIELD_FILTER_MAP object maps the dimension name "state.state_name" to the filter's key "State 📍". Then the showAndSendUserPrompt method uses the map to determine the dimension's name to filter on.

7. Control dashboard filters from chat

Lastly, let's look at how to enable the Chat component to control the embedded dashboard's filters.

Determine what filters to set

1. The Chat component's streamAndParseResponse method is always checking for a system message with the data results from Conversational Analytics.
2. Whenever the streamAndParseResponse method parses out a system message with data results, it checks to see if any dimensions in the data correspond to the dimensions in the filters.
3. If so, then the streamAndParseResponse method converts the data columns to dashboard filters. This time the method makes use of FIELD_FILTER_MAP again, but in reverse, converting from the dimension name to the filter's key. The filter's values are the values in the data column.

Send filter change event to embedded dashboard

4. With the desired dashboard filters, the streamAndParseResponse method calls the Chat component's setFilters method with the desired filters.
5. This calls the EmbedChat component's setDashboardFilters method, which sends two events, "dashboard:filters:update" with the filters and "dashboard:run" to the embedded dashboard in immediate succession using Embed SDK's send method.
6. The "dashboard:filters:update" event changes the embedded dashboard's filters while the "dashboard:run" event re-runs the dashboard's queries with the new filters.

You must send the "dashboard:run" after the "dashboard:filters:update" event. The "dashboard:filters:update" event does not automatically re-run the dashboard's queries.

8. Conclusion and take-aways

You've set up your own working example of an embedded Looker dashboard integrated with Conversational Analytics chat. You've learned how to enable natural language driven data exploration with your embedded Looker dashboard and Conversational Analytics.

• You built a chat component with the Looker Component library.
• You passed your embedded Looker dashboard's context to Conversational Analytics to ease data exploration.
• You enabled Conversational Analytics to control your embedded dashboard's filters for enhanced context while exploring data.

What's next

• Learn more about Conversational Analytics's capabilities.
• Update your Looker Embed Reference example app to work with your own embedded Looker dashboards.
• Try out the other embed use cases available in your locally running Looker Embed Reference example app!