Looker connector tools

  • Updated

The Looker connector tools in Optimizely Opal let you query Looker data directly in Opal Chat, agents, and workflows. After you add the Looker Opal connector tool and authenticate it in Optimizely Connect Platform (OCP), you can retrieve dashboards, run reports, search content, and use Looker data inside automated workflows.

Complete the following steps to enable Looker connector tools in Opal.

Add the Opal Looker Tool app in OCP

In the OCP App Directory, complete the following:

  1. Click Opal Looker Tool.

  2. Click Install App.

Because Looker uses API keys, authentication requires generating an API key pair in Looker and providing those credentials in OCP.

Generate an API key in Looker

In Looker, complete the following steps:

  1. Go to Admin > Users and Permissions > API Keys.
  2. Click New API Key to generate a key pair.
  3. Record the Client ID and Secret.
    • Treat the Secret as a password and store it securely.

See the Looker API authentication documentation for more information.

Authenticate the Looker connector tool in OCP

After you generate your Looker API key, authenticate the connector in OCP.

  1. Click the Opal Looker Tool connector in the OCP App Directory.
  2. Go to the Settings tab.
  3. Enter the following in Looker Authentication section:
    • Looker Client ID
    • Looker Client Secret
    • Looker Instance URL –  Example: https://your-company.looker.com

  4. Click Save.

Register the Looker connector tool in OCP

After you authenticate the Looker Opal app, complete the following steps in OCP:

  1. Go to Settings > Add to Opal.

  2. Click Add to Opal for each Opal instance you want to add the Looker connector tools.

You can now discover and use the Looker connector tools within Opal.

To remove the connection, click Remove from Opal.

Looker connector tools

After you add and register the Looker connector tools, you can call the following tools in Opal. Click on a tool's name to expand it and learn more about when to use the tool, required and optional parameters, and example prompts on how to call the tool. If you do not provide a required parameter, Opal prompts you for it.

Retrieve dashboards, Looks, and models

looker_get_all_dashboards – Retrieves all dashboards from your Looker instance.
  • When to use
    • Browse available dashboards in your Looker instance.
    • Get metadata about dashboards, such as their titles, descriptions, and creators.
    • Filter dashboards by specific folders or their deletion status.
    • Understand the overall structure and organization of dashboards within your Looker instance.
    • Audit dashboard usage and organization.
  • Parameters
    • (Optional) deleted – Lets you include dashboards that were soft-deleted (moved to trash). Set to true to see deleted dashboards or false (default) to see only active ones.
    • (Optional) fields – Specifies which pieces of information you want to retrieve for each dashboard. This can help keep the results clean and focused. Provide a comma-separated list of fields. If you leave it empty, Opal returns a default set of common fields. Useful fields include the following:
      • id
      • title
      • description
      • dashboard_filters
      • folder
      • user_id
      • created_at
      • updated_at
    • (Optional) folder_id – Filters the list to only show dashboards located within a specific folder.
    • (Optional) limit – Sets the maximum number of dashboards to return. Useful for getting a quick sample or for pagination.
    • (Optional) offset – Works with limit for pagination. It tells the tool how many dashboards to skip from the beginning of the list.
    • (Optional) sorts – Determines the order in which the dashboards are listed. Provide a comma-separated list of fields to sort by
  • Example prompts
    • List all the dashboards in Looker.
    • Show me the titles and descriptions of all dashboards.
    • Can you get me the first 10 dashboards, sorted by their creation date in descending order?
    • I need to see all dashboards, including any deleted ones.
    • Find all dashboards and tell me who created them and when they were last updated.
looker_get_dashboard – Retrieves detailed information about a dashboard by ID.
  • When to use
    • Get all the detailed information about a single, specific Looker dashboard.
    • Understand the structure and components of a dashboard, including its tiles, filters, and underlying queries.
    • Retrieve metadata like the dashboard's title, description, creation date, and last update.
    • Access the configuration details of a dashboard, perhaps to replicate it or understand how it is built.
  • Parameters
    • dashboard_id – Identifies the specific dashboard you are interested in with a unique number.
    • (Optional) fields – Lets you choose which specific pieces of information you want to see about the dashboard. Provide a comma-separated list of the fields you want. Useful fields include the following:
      • id
      • title
      • description
      • dashboard_elements – For tiles and components.
      • dashboard_filters – For filters.
      • folder – For its location.
      • user_id – For who created it.
      • created_at 
      • updated_at
  • Example prompts
    • Tell me everything about dashboard ID 123.
    • Can you get the details for dashboard 456, but only show me its title, description, and filters?
    • What are the dashboard elements and queries associated with dashboard 789?
    • I need to see the full configuration for dashboard 101. What information can you provide?
    • Show me the title, creation date, and last updated date for dashboard 2020 dashboard 2022 for dashboard 202.
looker_get_all_looks – Retrieves all saved Looks in your instance.
  • When to use
    • Get a list of all saved reports (called Looks) in your Looker instance.
    • Discover what reports are available that might answer your business questions.
    • Find predefined dashboards and analyses.
    • Get quick insights from reports that have already been built.
  • Parameters
    • (Optional) limit – How many Looks are returned in a single request. Useful if you only want to see a few examples or if you're dealing with a very large number of Looks.
    • (Optional) offset – Used for pagination, meaning if there are many Looks, you can ask for them in chunks. This tells the tool to skip a certain number of Looks from the beginning of the list.
  • Example prompts
    • List all the saved Looks in Looker.
    • Show me the first 25 Looks available.
    • Can you get me all the Looks, but start after the first 100?
    • What reports are available in Looker?
    • I need to see a list of all existing analyses that list all the looks.
looker_get_all_models – Retrieves all available LookML models. Models are top-level containers that define data connections and explores. 
  • When to use
    • Get a list of all the LookML models available in your Looker instance.
    • Understand the structure of your data and how it is organized.
    • Discover what data sources are connected and available for querying.
    • Find the right model to use when you plan to build new queries or reports.
  • Parameters
    • (Optional) limit – Lets you control the maximum number of LookML models that are returned in the list.
  • Example prompts
    • List all the LookML models available in Looker.
    • Show me all the data models.
    • Can you give me a list of all models, but only show the first 5?
    • What are the different data models we have in Looker?
looker_get_lookml_model_explore – Retrieves metadata for an explore within a LookML model. An explore defines the data structure and relationships available for querying. 
  • When to use
    • Building dynamic query interfaces.
    • Understanding data relationships.
    • Validating field names before running queries.
    • Creating intelligent query builders.
    • Discovering available fields for queries.
  • Parameters
    • explore_name – Name of the explore within the model. 
    • lookml_model – Name of the LookML model containing the explore.
    • (Optional) fields – Comma-separated list of fields to include in the response. Controls which metadata is returned. Useful for performance optimization or when you only need specific information. Common useful fields include the following:
      • dimensions
      • measures
      • dimension_groups
      • joins
      • sql_table_name
      • description
      • hidden
  • Example prompts
    • Tell me about the 'orders' explore in the 'ecommerce' model.
    • What dimensions and measures are available in the 'users' explore of the 'customer_analytics' model?
    • Can you show me the joins defined in the 'events' explore within the 'web_analytics' model?
    • I need to see all the metadata for the 'products' explore in the 'inventory' model.
    • What are the available fields for the 'sales_facts' explore in the 'sales' model, focusing on dimensions and measures?

Run reports and queries

looker_run_look – Executes a saved Look (report) and returns data results.
  • When to use
    • Run existing reports to get current data.
    • Access predefined analysis and dashboards.
    • Get formatted results from saved queries.
    • Answer questions using previously built reports.
  • Parameters
    • look_id – The unique number that identifies a specific saved report (Look) in Looker. You can use the looker_get_all_looks from the Retrieve dashboards, Looks, and models section to find the available Look IDs.
    • (Optional) result_format – The format you want the report results in. Options include the following: 
      • json – Structured JSON data (recommended for most cases, the default).
      • csv – Comma-separated values (if you specifically need CSV).
      • txt – Tab-separated text.
    • (Optional) apply_formatting – Whether to apply Looker's default formatting (like currency symbols, date formats) to the data. Set to true if you want the data to look nice for display (this is generally recommended). Set to false if you need the raw data for further processing.
    • (Optional) limit – The maximum number of rows you want to see in the results.
  • Example prompts
    • Run the Look with ID 123 and give me the results in CSV format.
    • Can you execute Look 456 and apply the standard formatting?
    • Get the data from Look 789, but only show me the first 50 rows.
    • I need the results from Look 1011, formatted as JSON.
looker_run_query – Executes a Looker query to retrieve data from your data warehouse.
  • When to use
    • Answer specific data questions.
    • Explore data dynamically.
    • Build custom reports.
    • Get fresh data. 
  • Parameters
    • model – The name of the LookML model you want to query. Use the looker_get_all_models tool from the Retrieve dashboards, Looks, and models section to get a list of available models.
    • view – The specific "view" or "explore" within the model that contains the data fields you are interested in. Use the looker_get_lookml_model_explore tool from the Retrieve dashboards, Looks, and models section with a model name to see available views and their fields.
    • fields – The specific data points (dimensions and measures) you want to see in your report. Provide a comma-separated list of field names, each in the format VIEW_NAME.FIELD_NAME.
    • (Optional) filters – Criteria to narrow down your data. This is where you specify conditions like date ranges, specific values, or exclusions. This is a JSON string where keys are field names (view.field) and values are the filter expressions. 
      • Fuzzy matching – Opal uses a fuzzy match pattern by default (for example, %value%) for string filters unless you explicitly ask for an exact match. This helps find partial matches.
      • Case sensitivity – Looker's database is case-sensitive, so it preserves the original case in your filter values.
    • (Optional) sorts – How you want your results ordered.
    • (Optional) limits – The maximum number of rows you want in your final result.
    • (Optional) result_format – The format you want the query results in. Options include the following: 
      • json – Structured JSON data (recommended for most cases, the default).
      • csv – Comma-separated values (if you specifically need CSV).
      • txt – Tab-separated text.
    • (Optional) apply_formatting – Whether to apply Looker's default formatting to the data values.
  • Example prompts
    • Show me the orders.id, orders.created_date, and orders.total_amount from the ecommerce model and orders view for orders placed this month.
    • Can you get me the users.email and users.country from the users view in the marketing model, but only for users in 'United States' or 'Canada', and sort them by users.email alphabetically?
    • I need a list of products.name and products.category from the inventory model and products view, but only for products where the products.stock_level is less than 10, and limit the results to 50.
    • Find the events.name and events.count from the analytics model and events view for events that happened yesterday, and I want an exact match for events.name being 'page_view'.
    • What are the orders.id, orders.status, and users.email for all orders in the ecommerce model and orders view where the orders.status is 'pending' or 'processing', and the orders.total_amount is greater than 50?
looker_get_query – Retrieves a saved query by ID to retrieve the query definition and metadata.
  • When to use
    • Inspect existing query definitions – Understand how a specific query is built, including its fields, filters, and sorting.
    • Understand how a query is constructed – See a query ID's underlying logic without running the query itself.
    • Get query metadata – Retrieve information like when it was created, who owns it, and its unique ID.
    • Retrieve query configuration for modification – See a query's current state if you are planning to make changes to an existing query.
    • Debug or analyze existing queries – Understand why a query might be returning certain results or behaving in a particular way.
  • Parameters
    • query_id – The unique numerical identifier for the saved query you want to retrieve. You can find query IDs in Looker URLs when you are viewing a saved query.
    • (Optional) fields – A comma-separated list of specific pieces of information you want to get about the query. This helps you get only what you need and can make the response faster. Common useful fields include the following:
      • id:– The query's unique ID.
      • model – The LookML model the query uses.
      • view – The view or explore within the model.
      • fields – The dimensions and measures selected in the query.
      • filters – The filters applied to the query.
      • sorts – How the query results are sorted.
      • limit – Any row limit set for the query.
      • created_at – When the query was created.
      • user_id – The ID of the user who created the query.
  • Example prompts
    • Can you get me the details of query ID 123?
    • Show me the fields, filters, and sorts for query 456.
    • What model and view does query 789 use?
    • I need to see all the information about query 1011, including who created it and when.
looker_create_look_render_task – Creates a render task to generate exports (PDF, PNG, CSV, and so on) of a Look.
  • When to use
    • Generate printable reports – Create PDF versions of your Looks.
    • Create image thumbnails of visualizations – Get PNG or JPG images of your Looker charts.
    • Export data for external analysis – Get data in CSV, XLSX, JSON, or TXT formats.
    • Schedule automated report generation – Regularly produce reports in a specific format.
    • Create downloadable content for users – Provide a way for others to download data or reports.
  • Parameters
    • look_id – The unique identifier for the Look (saved report) you want to render. Use the looker_get_all_looks tool from the Retrieve dashboards, Looks, and models section to find the IDs of available Looks.
    • result_format – The file format you want the rendered output to be in. Options include the following:
      • pdf – PDF document (default page size A4).
      • png – PNG image (default 545x842 pixels).
      • jpg – JPEG image (default 545x842 pixels).
      • csv – CSV data file.
      • xlsx – Excel spreadsheet.
      • json – JSON data.
      • txt – Plain text data.
    • (Optional) width – The width in pixels for image formats (PNG, JPG).
    • (Optional) height – The height in pixels for image formats (PNG, JPG).
    • (Optional) pdf_landscape – Sets the orientation for PDF documents.
    • (Optional) pdf_paper_size – Sets the paper size for PDF documents. Options include the following:
      • letter – US Letter (8.5" x 11").
      • legal – US Legal (8.5" x 14").
      • a4 – A4 (210mm x 297mm) – Default
      • a3 – A3 (297mm x 420mm).
  • Example prompts
    • Generate a PDF of Look ID 123.
    • I need a PNG image of Look 456. Can you make it 1200 pixels wide?
    • Export the data from Look 789 as an Excel spreadsheet.
    • Create a landscape PDF of Look 1011 using A3 paper size.
    • Can you render Look 222 as a JPG with a width of 800 and a height of 600 pixels?
    • I want the raw JSON data from Look 333.
looker_get_render_task – Retrieves the status and results of a render task created with CreateLookRenderTask.
  • When to use
    • Monitor render task progress – See if your PDF, image, or data export is still being generated or if it is finished.
    • Download completed files – Provides the direct download link for your rendered file.
    • Handle render failures – Check the status of a failed task to understand if there was an error.
    • Build status dashboards – Track the completion of automated reports.
  • Parameters
    • task_id – The unique identifier for the rendering task that was returned to you when you used the looker_create_look_render_task tool.
  • Example prompts
    • Check the status of render task abc123def456.
    • Is render task xyz789uvw012 complete yet?
    • What is the status of my report generation task task_id_example?
    • Can you get me the download link for task render_task_123?

Search content

looker_search_dashboards – Searches and filters dashboards in your Looker instance using various criteria.
  • When to use
    • Find dashboards by keywords in title or description.
    • Filter dashboards by creator, folder, or dates.
    • Build dashboard browsing and discovery features.
    • Audit dashboard usage and organization.
    • Find recently created or updated dashboards.
  • Parameters
    • q – Search term to filter dashboards by text content. Searches across dashboard titles, descriptions, and other text fields. Use quotes for exact phrases or combine terms with spaces.
    • (Optional) created_at – Filter dashboards created on or after this date. Use YYYY-MM-DD format.
    • (Optional) deleted – Flag to include deleted dashboards in results
    • (Optional) fields – Comma-separated list of fields to include in the response. Common useful fields include the following: 
      • id
      • title
      • description
      • folder
      • user_id
      • created_at
      • updated_at
      • dashboard_filters
    • (Optional) folder_id – Only return dashboards in the specified folder.
    • (Optional) limit – Maximum number of dashboards to return. Use for pagination or to limit large result sets.
    • (Optional) offset – Number of results to skip (for pagination). Use with limit to paginate through large result sets.
    • (Optional) sorts – Comma-separated list of fields to sort results by.
    • (Optional) updated_at – Filter dashboards updated on or after this date. Use YYYY-MM-DD format.
    • (Optional) user_id – Only return dashboards created by the specified user. 
  • Example prompts
    • Search for dashboards related to 'sales performance'.
    • Find all dashboards created by user ID 123 and updated after 2023-01-01.
    • List the top 10 most recently created dashboards.
    • Show me dashboards in folder 'Marketing Reports'.
    • Are there any deleted dashboards containing 'Q4' in their title?
looker_search_looks – Searches and filters Looks in your Looker instance using various criteria.
  • When to use
    • Find Looks by keywords in title or description
    • Filter Looks by creator, folder, or dates
    • Build Look browsing and discovery features
    • Audit Look usage and organization
    • Find recently created or updated queries
  • Parameters
    • q – Search term to filter Looks by text content. Searches across Look titles, descriptions, and other text fields. Use quotes for exact phrases or combine terms with spaces.
    • (Optional) created_at – Filter Looks created on or after this date. Use YYYY-MM-DD format. 
    • (Optional) deleted – Flag to include deleted Looks in results. Default: false (only active Looks).
    • (Optional) fields – Comma-separated list of fields to include in the response. Common useful fields: include the following:
      • id
      • title
      • description
      • folder
      • user_id
      • created_at
      • updated_at
      • query
    • (Optional) folder_id – Folder ID to filter Looks by location. Only returns Looks in the specified folder.
    • (Optional) limit  – Maximum number of Looks to return. Use for pagination or to limit large result sets.
    • (Optional) offset – Number of results to skip (for pagination). Use with limit to paginate through large result sets.
    • (Optional) sorts – Comma-separated list of fields to sort results by. 
    • (Optional) updated_at – Filter Looks updated on or after this date. Use YYYY-MM-DD format. 
    • (Optional) user_id – Returns Looks created by the specified user.
  • Example prompts
    • Search for Looks related to 'sales analysis'.
    • Find all Looks created by user ID 456 and updated after 2023-06-01.
    • List the top 5 most recently updated Looks.
    • Show me Looks in folder 'Financial Reports'.
    • Are there any deleted Looks containing 'Q1' in their title?
looker_search_models – Searches and filters LookML models in your Looker instance using various criteria.
  • When to use
    • Find models by keywords in name, label, or description.
    • Browse available data models for exploration.
    • Build model discovery and navigation features.
    • Audit model organization and usage.
    • Find models for specific data domains.
  • Parameters
    • q – Search term to filter models by text content. Searches across model names, labels, and descriptions. Use quotes for exact phrases or combine terms with spaces.
    • (Optional) fields – Comma-separated list of fields to include in the response. Common useful fields include the following:
      • name
      • label
      • description
      • project_name
      • explores
      • allowed_db_connection_names
    • (Optional) limit – Maximum number of models to return. Use for pagination or to limit large result sets. 
    • (Optional) offset – Number of results to skip (for pagination). Use with limit to paginate through large result sets.
    • (Optional) sorts – Comma-separated list of fields to sort results by. 
  • Example prompts
    • Search for LookML models related to 'customer data'.
    • Find models that have 'marketing' in their description.
    • List all models and sort them by name.
    • Show me the top 5 models containing 'sales' in their name or label.
    • Are there any models with 'ecommerce' in their name, and include their explores?
looker_search_content – Searches for content across all content types in your Looker instance.
  • When to use
    • Find content by name or keyword across different types.
    • Discover relevant dashboards and reports.
    • Locate content by creator or folder.
    • Manage and organize content.
  • Parameters
    • (Optional) created_at – Filter by creation date. Use YYYY-MM-DD format.
    • (Optional) favorites – Filter to only show favorited content. Set to true to filter on your favorited content, false (default) for all content.
    • (Optional) fields – Comma-separated list of fields to return for each content item. Common fields include the following: 
      • id
      • type
      • title
      • description
      • url
      • folder
      • user
      • created_at
      • updated_at
      • view_count
      • favorited
    • (Optional) folder_id – Filter content to a specific folder. Only returns content within the specified folder.
    • (Optional) limit – Maximum number of content items to return.
    • (Optional) offset – Number of items to skip for pagination. Use with limit for paging through large result sets.
    • (Optional) q – Search term to filter content by. Searches across content titles, descriptions, and other text fields. Supports partial matches and is case-insensitive.
    • (Optional) sorts – Sort order for results. Options include title, created_at desc, updated_at desc, view_count desc. Default is relevance-based sorting.
    • (Optional) types – Comma-separated list of content types to include in search. Supported types: dashboard, look, folder, query, space. If not specified, searches all content types.
    • (Optional) updated_at – Filter by last updated date. Use YYYY-MM-DD format.
    • (Optional) user_id – Filter content by creator user ID. Only returns content created by the specified user.ne
  • Example prompts
    • Search for all content related to 'marketing campaigns'.
    • Find dashboards and Looks that were updated after 2024-01-01.
    • List all content created by user ID 789 in the 'Sales' folder.
    • Show me my favorited reports.
    • What content types are available that mention 'customer retention'?
    • Find any content with 'Q3 results' in the title or description, sorted by creation date descending.

Retrieve users and attributes

looker_get_all_users – Retrieves all users from your Looker instance.
  • When to use
    • Get an overview of all users in your Looker instance.
    • Audit user access and permissions.
    • Generate user reports.
    • Find specific users by browsing the full list.
    • Monitor user account status.
  • Parameters
    • (Optional) limit – Maximum number of users to return in a single request. Use this to control the size of the response and implement pagination.
    • (Optional) offset – Starting position for pagination. Use this with limit to implement pagination through large user lists. For example, offset=50 with limit=25 gets users 51-75.
  • Example prompts
    • List all users in Looker.
    • Show me the first 50 users in the system.
    • Get users 101 through 200 from the user list.
    • Can you provide a list of all Looker users, 25 at a time?
looker_get_user_by_id – Retrieves detailed information about a specific Looker user by their user ID. This retrieves comprehensive information about a single user including their basic profile, account status, roles, group memberships, and settings.
  • When to use
    • Get detailed information about a specific user.
    • Look up user profile and settings.
    • Verify user permissions and roles.
    • Troubleshoot user-specific issues.
  • Parameters
    • user_id – The unique identifier for the Looker user you want to retrieve. This is the numeric user ID that can be found from user listings or other user-related API responses.
  • Example prompts
    • Get details for the user with ID 123.
    • Show me the profile information for user 456.
    • What are the roles and permissions for user ID 789?
    • Can you retrieve the full details for user 101?
looker_get_all_user_attributes – Retrieves all user attributes configured in Looker. User attributes are variables that can be used to customize content and data access for different users. 
  • When to use
    • Row-level security and data filtering.
    • Personalized dashboard content.
    • User-specific default values.
    • Dynamic content based on user properties.
    • Access control and permissions.
  • Parameters
    • (Optional) fields – Comma-separated list of fields to return for each user attribute. Available fields include the following: 
      • id
      • name
      • label
      • type
      • default_value
      • user_can_edit
      • user_can_view
      • system
      • hidden_value_domain_whitelist
      • value_is_hidden
    • (Optional) sorts – Sort order for the user attributes list. Options include the following:
      • "name" – Alphabetical A-Z.
      • "name desc" – Alphabetical Z-A.
      • "label"
      • "type
      • "id"
  • Example prompts
    • List all user attributes in Looker.
    • Show me the name, label, and type of all user attributes.
    • Sort all user attributes by name in descending order.
    • What user attributes are configured, and can users edit them?
    • Retrieve all user attributes, including their default values and whether they are system attributes.

If you use Opti ID, administrators can turn off generative AI in the Opti ID Admin Center. See Turn generative AI off across Optimizely applications.