Skip to main content

​
Looker Integration

Oxy integrates with Looker to enable agents and procedures to query Looker explores directly. The integration supports metadata synchronization, LLM-powered query generation, and procedure automation.

​
Prerequisites

  • A Looker instance with API access enabled
  • API credentials (client ID and client secret) from your Looker admin panel
  • Oxy CLI installed

​
Configuration

Add your Looker integration to config.yml: 
integrations:
  my_looker:
    type: looker
    client_id_var: LOOKER_CLIENT_ID
    client_secret_var: LOOKER_CLIENT_SECRET
    base_url: https://mycompany.looker.com:19999
    explores:
      - model: ecommerce
        name: orders
        description: Order analytics explore
      - model: ecommerce
        name: users
        description: User analytics explore

​
Configuration Options

  • client_id_var - Name of the environment variable storing your Looker API client ID
  • client_secret_var - Name of the environment variable storing your Looker API client secret
  • base_url - Your Looker instance URL including the API port (typically :19999)
  • explores - List of Looker explores to make available
    • model - The LookML model name
    • name - The explore name
    • description - Optional description for agent context

​
Authentication

Oxy authenticates with Looker using OAuth 2.0 client credentials. Store your credentials as environment variables: 
export LOOKER_CLIENT_ID="your_client_id"
export LOOKER_CLIENT_SECRET="your_client_secret"
To generate API credentials in Looker:
1

Navigate to Looker Admin

Go to your Looker instance and navigate to Admin > Users.
2

Edit API keys

Select your user (or a service account) and click Edit Keys under the API section.
3

Create new API credentials

Click New API Key. Copy the Client ID and Client Secret — the secret is only shown once.
4

Set environment variables

Export the credentials in your shell or add them to your .env file:
export LOOKER_CLIENT_ID="your_client_id"
export LOOKER_CLIENT_SECRET="your_client_secret"

​
Metadata Synchronization

Before querying, you need to sync explore metadata from Looker. This downloads field definitions (dimensions, measures, views) so that agents have context for generating queries.

​
Sync Commands

# Sync all configured explores
oxy looker sync

# Sync a specific integration
oxy looker sync --integration my_looker

# Sync a specific model
oxy looker sync --integration my_looker --model ecommerce

# Sync a specific explore
oxy looker sync --integration my_looker --model ecommerce --explore orders

# Force re-sync (overwrite existing metadata)
oxy looker sync --force

​
How Metadata Storage Works

Synced metadata is stored in two layers:
  • Base metadata (auto-generated, git-ignored): ~/.local/share/oxy/.looker/<integration>/<model>/<explore>.yml
  • Overlay metadata (user-managed, version-controlled): looker/<integration>/<model>/<explore>.yml in your project directory
The overlay file lets you add custom descriptions, agent hints, and query examples that are merged with the base metadata at runtime.

​
Overlay Metadata Example

# looker/my_looker/ecommerce/orders.yml
description: "Order analytics explore"
views:
  - name: orders
    dimensions:
      - name: orders.created_date
        agent_hint: "Supports relative dates like 'last 7 days'"
        examples:
          - query: "Orders from Q4 2025"
            filters:
              orders.created_date: "2025-10-01 to 2025-12-31"
    measures:
      - name: orders.total_revenue
        agent_hint: "Primary revenue metric"

​
Using Looker in Agents

Add a Looker tool to your agent configuration to let the agent query Looker explores: 
tools:
  - name: query_orders
    type: looker
    integration: my_looker
    model: ecommerce
    explore: orders
The agent receives synced metadata (dimensions, measures, descriptions, and any overlay hints) as context. It uses this to generate Looker query parameters — including fields, filters, and sorts — and executes them via the Looker API.

​
Looker Filter Syntax

Looker uses its own filter syntax, not SQL expressions. When writing overlay hints for agents, include examples using native Looker filter syntax:
Filter TypeExample
Relative dates"last 30 days", "yesterday", "this quarter"
Date ranges"2024-01-01 to 2024-12-31"
String matching"value", "%partial%"
Numeric comparisons">=100", "[10,20]"

​
Using Looker in Agentic Workflows

An agentic workflow (.aw.yml) lets an LLM autonomously plan and execute Looker queries. Add a looker_query transition to wire up the Looker explore: 
model: openai-5.2

start:
  mode: plan
  instruction: |
    ## Role
    You are a Looker analytics assistant.

    ## Goal
    Use the available Looker explore to answer the user's question with a query result.

    ## Available Actions
    - **looker_query**: Run a Looker query against the configured integration/model/explore

    ## Guidelines
    - Prefer the `looker_query` action to retrieve data.
    - Apply filters and limits when needed.
    - End after returning a clear answer from the query result.
  next: [looker_query]

end:
  mode: synthesize

transitions:
  - type: looker_query
    integration: my_looker
    model: ecommerce
    explore: orders
The agent will automatically receive explore metadata as context, generate the appropriate query parameters (fields, filters, sorts), execute the query via the Looker API, and synthesize the results into a response.

​
Using Looker in Procedures

Add a Looker query task to your procedure: 
tasks:
  - name: get_sales_data
    type: looker_query
    integration: my_looker
    model: ecommerce
    explore: orders
    fields:
      - orders.created_date
      - orders.total_revenue
      - orders.count
    filters:
      orders.created_date: "last 30 days"
    sorts:
      - field: orders.created_date
        direction: desc
    limit: 1000
    export:
      format: csv
      path: ./output/sales_data.csv

​
Query Parameters

  • fields - List of dimension and measure names to include (use full view.field_name format)
  • filters - Map of field names to Looker filter expressions
  • filter_expression - Optional filter expression for complex OR conditions
  • sorts - List of sort objects, each with field and direction (asc or desc, defaults to asc)
  • limit - Maximum number of rows to return (use -1 for unlimited)

​
CLI Commands

​
Test Connection

oxy looker test --integration my_looker

​
List Synced Explores

# List all synced explores
oxy looker list

# List explores for a specific integration
oxy looker list --integration my_looker

# List explores for a specific model
oxy looker list --integration my_looker --model ecommerce

​
Troubleshooting

  • Authentication errors - Verify your client ID and secret are correct and that the environment variables are exported. API credentials may expire if rotated in the Looker admin panel.
  • Connection refused - Ensure the base_url includes the correct port (Looker API typically runs on port 19999).
  • Empty metadata after sync - Check that the explores listed in your configuration exist in Looker and that your API credentials have permission to access them.
  • Query errors with filters - Looker uses its own filter syntax, not SQL. Use expressions like "last 30 days" instead of SQL date functions.