Connect to Looker

You can connect a data agent to Looker by using the Conversational Analytics API to let users query data in natural language and receive answers that are grounded in your curated LookML models and business logic.

You can use the Python SDK or HTTP to connect to Looker to define your connected Explores and configure authentication credentials.

Data agents that you create with the API are managed as Google Cloud resources and don't appear in the Looker UI. To create and manage data agents in Looker, see Create and manage Explore data agents.

Before you begin

Before you connect a data agent to Looker, complete the following tasks:

  1. Enable the Conversational Analytics API in your Google Cloud project.
  2. Verify that you have the required Identity and Access Management (IAM) roles.
  3. Ensure that your Looker instance meets the prerequisites for Conversational Analytics and that you have access to the LookML models and Explores that you want to query.

Required roles

To get the permissions that you need to connect a data agent to Looker and query Explores, ask your administrator to grant you the following IAM roles:

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

In addition to IAM roles, you must have appropriate permissions in Looker. To connect to and query Looker Explores, you must be assigned a Looker role that contains the gemini_in_looker and access_data permissions for the LookML models that you interact with.

Connect to Looker Explores

You can connect up to five Looker Explores at a time with the Conversational Analytics API.

A data agent queries one Explore at a time and can't join data across multiple Explores in a single query. However, an agent can query multiple Explores across a conversation to answer follow-up questions or multi-part prompts. For example, if a prompt requires data from both an orders Explore and an inventory Explore, the agent queries each one sequentially and combines the results in a single response.

To improve response accuracy, you can optionally define golden queries that guide how the agent queries your Explores. For more information, see Define data agent context for Looker data sources.

The following code samples show how to define a connection to multiple Looker Explores:

Python SDK

looker_instance_uri = "INSTANCE_URI"

looker_explore_reference_1 = geminidataanalytics.LookerExploreReference()
looker_explore_reference_1.looker_instance_uri = looker_instance_uri
looker_explore_reference_1.lookml_model = "MODEL"
looker_explore_reference_1.explore = "EXPLORE"

# Optional: Define additional Explores (up to 5 total)
looker_explore_reference_2 = geminidataanalytics.LookerExploreReference()
looker_explore_reference_2.looker_instance_uri = looker_instance_uri
looker_explore_reference_2.lookml_model = "MODEL_2"
looker_explore_reference_2.explore = "EXPLORE_2"

datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.looker.explore_references = [
    looker_explore_reference_1,
    looker_explore_reference_2,
]

Replace the sample values as follows:

  • INSTANCE_URI: The complete URL of your Looker instance (for example, https://mycompany.looker.com).
  • MODEL: The name of the LookML model that includes the Explore that you want to connect to.
  • EXPLORE: The name of the Looker Explore that you want the data agent to query.
  • MODEL_2: An optional second LookML model name if you are connecting multiple Explores. You can repeat this variable for up to five Explores.
  • EXPLORE_2: An optional second Looker Explore name if you are connecting multiple Explores. You can repeat this variable for up to five Explores.

HTTP

looker_instance_uri = "INSTANCE_URI"
looker_data_source = {
    "looker": {
        "explore_references": [
            {
                "looker_instance_uri": looker_instance_uri,
                "lookml_model": "MODEL",
                "explore": "EXPLORE",
            },
            # Optional: Add up to 5 total Explore references
            {
                "looker_instance_uri": looker_instance_uri,
                "lookml_model": "MODEL_2",
                "explore": "EXPLORE_2",
            },
        ],
    }
}

Replace the sample values as follows:

  • INSTANCE_URI: The complete URL of your Looker instance (for example, https://mycompany.looker.com).
  • MODEL: The name of the LookML model that includes the Explore that you want to connect to.
  • EXPLORE: The name of the Looker Explore that you want the data agent to query.
  • MODEL_2: An optional second LookML model name if you are connecting multiple Explores. You can repeat this variable for up to five Explores.
  • EXPLORE_2: An optional second Looker Explore name if you are connecting multiple Explores. You can repeat this variable for up to five Explores.

Authenticate to Looker

To run queries against your connected Explores, a data agent must authenticate to your Looker instance. Because credentials aren't stored with the data agent, you provide Looker credentials in each chat request, as described in Build a data agent using HTTP and Build a data agent using the Python SDK.

You can format credentials by using either API keys or an OAuth access token.

Authenticate with API keys

A Looker API key consists of a client ID and a client secret that are associated with a Looker user account. When you authenticate by using an API key, the data agent executes queries with the permissions that are assigned to that user account.

The following code samples show how to format credentials by using an API key:

Python SDK

credentials = geminidataanalytics.Credentials()
credentials.oauth.secret.client_id = "CLIENT_ID"
credentials.oauth.secret.client_secret = "CLIENT_SECRET"

Replace the sample values as follows:

  • CLIENT_ID: The client ID of your Looker API key.
  • CLIENT_SECRET: The client secret of your Looker API key.

HTTP

looker_credentials = {
    "oauth": {
        "secret": {
            "client_id": "CLIENT_ID",
            "client_secret": "CLIENT_SECRET",
        }
    }
}

Replace the sample values as follows:

  • CLIENT_ID: The client ID of your Looker API key.
  • CLIENT_SECRET: The client secret of your Looker API key.

Authenticate with an access token

If your application uses OAuth to authenticate to Looker, you can provide an access token in your credentials rather than an API key.

The following code samples show how to format credentials by using an access token:

Python SDK

credentials = geminidataanalytics.Credentials()
credentials.oauth.token.access_token = "ACCESS_TOKEN"

Replace ACCESS_TOKEN with the OAuth access token that you generate to authenticate to Looker.

HTTP

looker_credentials = {
    "oauth": {
        "token": {
            "access_token": "ACCESS_TOKEN",
        }
    }
}

Replace ACCESS_TOKEN with the OAuth access token that you generate to authenticate to Looker.

What's next