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.

To configure your data source, first define references to your Looker Explores by using the Python SDK or HTTP. Then, provide these references when you create a persistent data agent or send a stateless chat request with inline context.

You also provide Looker credentials in each chat request, as described in Authorize requests to Looker.

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. Verify 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.
  4. Get a Looker API key or an access token to authorize the data agent's requests to your instance. To decide which to use, see Choose an authorization method.

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 need permissions in Looker. The Looker user or service account whose credentials are used to authenticate must have a Looker role that includes the following permissions for the LookML models that you query:

To configure roles, go to Admin > Roles in your Looker instance.

Connect to Looker Explores

You can connect up to five Looker Explores at a time with the Conversational Analytics API. All Explores in a data source must be on the same Looker instance, and each Explore reference must identify that instance in the same way.

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 define golden queries that guide how the agent queries your Explores. For more information, see Define data agent context for Looker data sources.

How you identify your instance in each Explore reference depends on how you connect to the instance.

Connect to an instance that has a public URL

If your Looker instance has a public URL, set the looker_instance_uri field (Python SDK) or the lookerInstanceUri field (HTTP) in each Explore reference.

The following code samples show how to define a connection to multiple Explores on an instance that has a public URL:

Python SDK

from google.cloud import geminidataanalytics

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,
]

# Attach the data source to published context
published_context = geminidataanalytics.Context()
published_context.datasource_references = datasource_references

Replace the sample values as follows:

  • INSTANCE_URI: The complete URL of your Looker instance (for example, https://example.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: Optional: The name of the LookML model that includes the second Explore. This model can be the same as MODEL.
  • EXPLORE_2: Optional: The name of a second Looker Explore. To connect more Explores, add a reference for each one, up to five in total.

HTTP

looker_instance_uri = "INSTANCE_URI"

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

# Attach the data source to published context
published_context = {
    "datasourceReferences": looker_data_source,
}

Replace the sample values as follows:

  • INSTANCE_URI: The complete URL of your Looker instance (for example, https://example.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: Optional: The name of the LookML model that includes the second Explore. This model can be the same as MODEL.
  • EXPLORE_2: Optional: The name of a second Looker Explore. To connect more Explores, add a reference for each one, up to five in total.

Connect to an instance that uses only private connections

If your Looker (Google Cloud core) instance uses only private connections, set the private_looker_instance_info field (Python SDK) or the privateLookerInstanceInfo field (HTTP) in each Explore reference. This field contains the instance ID and Service Directory name. You must also authorize requests by using an access token.

The following code samples show how to define a connection to multiple Explores on an instance that uses only private connections:

Python SDK

from google.cloud import geminidataanalytics

private_instance = geminidataanalytics.PrivateLookerInstanceInfo()
private_instance.looker_instance_id = "INSTANCE_ID"
private_instance.service_directory_name = "SERVICE_DIRECTORY_NAME"

looker_explore_reference_1 = geminidataanalytics.LookerExploreReference()
looker_explore_reference_1.private_looker_instance_info = private_instance
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.private_looker_instance_info = private_instance
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,
]

# Attach the data source to published context
published_context = geminidataanalytics.Context()
published_context.datasource_references = datasource_references

Replace the sample values as follows:

  • INSTANCE_ID: The ID of your Looker (Google Cloud core) instance, in the following format: projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_NAME.
  • SERVICE_DIRECTORY_NAME: The resource name of the Service Directory service for your Looker (Google Cloud core) instance, in the following format: projects/PROJECT_ID/locations/LOCATION/namespaces/NAMESPACE/services/SERVICE. To get this name, give your instance ID to your Looker customer engineer.
  • 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: Optional: The name of the LookML model that includes the second Explore. This model can be the same as MODEL.
  • EXPLORE_2: Optional: The name of a second Looker Explore. To connect more Explores, add a reference for each one, up to five in total.

HTTP

private_instance = {
    "lookerInstanceId": "INSTANCE_ID",
    "serviceDirectoryName": "SERVICE_DIRECTORY_NAME",
}

looker_data_source = {
    "looker": {
        "exploreReferences": [
            {
                "privateLookerInstanceInfo": private_instance,
                "lookmlModel": "MODEL",
                "explore": "EXPLORE",
            },
            # Optional: Add up to 5 total Explore references
            {
                "privateLookerInstanceInfo": private_instance,
                "lookmlModel": "MODEL_2",
                "explore": "EXPLORE_2",
            },
        ],
    }
}

# Attach the data source to published context
published_context = {
    "datasourceReferences": looker_data_source,
}

Replace the sample values as follows:

  • INSTANCE_ID: The ID of your Looker (Google Cloud core) instance, in the following format: projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_NAME.
  • SERVICE_DIRECTORY_NAME: The resource name of the Service Directory service for your Looker (Google Cloud core) instance, in the following format: projects/PROJECT_ID/locations/LOCATION/namespaces/NAMESPACE/services/SERVICE. To get this name, give your instance ID to your Looker customer engineer.
  • 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: Optional: The name of the LookML model that includes the second Explore. This model can be the same as MODEL.
  • EXPLORE_2: Optional: The name of a second Looker Explore. To connect more Explores, add a reference for each one, up to five in total.

Authorize requests to Looker

To run queries against your connected Explores, the data agent needs Looker credentials that authorize its requests to your Looker instance. Credentials aren't stored with the data agent, so you provide them in the credentials field of each chat request. For examples, see Build a data agent using HTTP and Build a data agent using the Python SDK.

Choose an authorization method

You can authorize requests by using either a Looker API key or an OAuth access token. If your Looker (Google Cloud core) instance uses only private connections, you must use an access token.

API keys use the permissions and access levels of the user account that the key is associated with. API keys can be useful if you're building an application in which everyone shares the same level of access.

An access token applies the target user's LookML row-level and column-level permissions (for example, access_filters, access_grants, and sql_always_where). An access token is useful for a multi-tenant application.

Use the following table to choose how to authorize requests:

User type Authorization method For Looker (original) For Looker (Google Cloud core) For Looker (Google Cloud core) that uses only private connections Description
Embed users Access token login_user login_user login_user Respects the target user's LookML row-level and column-level permissions (for example, access_filters, access_grants, and sql_always_where).
Standard users Access token

login_user

Or

OAuth client

OAuth client OAuth client Respects the target user's LookML row-level and column-level permissions (for example, access_filters, access_grants, and sql_always_where).
Looker API-only service account API key Client ID and secret Client ID and secret Not supported All users share the same level of access to Looker.

Connect with Looker API keys

A Looker API key consists of a client ID and a client secret that are associated with a Looker user account.

For more information about generating Looker API keys, see Admin settings - Users. For more information about authentication methods and managing Looker API keys, see Looker API authentication.

The following code samples show how to specify your credentials by using an API key. Pass the resulting object in the credentials field of your chat request:

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": {
            "clientId": "CLIENT_ID",
            "clientSecret": "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.

Connect 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.

You generate an access token by sending a request to the login endpoint of the Looker API. For more information about generating an access token, see Looker API authentication and Present client credentials to obtain an authorization token.

The following code samples show how to specify your credentials by using an access token. Pass the resulting object in the credentials field of your chat request:

Python SDK

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

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

HTTP

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

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

What's next