Looker Integration

Oxygen integrates with Looker to enable agents and automations to query Looker explores directly. The integration supports metadata synchronization, LLM-powered query generation, and automation support.

Prerequisites

A Looker instance with API access enabled
API credentials (client ID and client secret) from your Looker admin panel
Oxygen 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

Oxygen 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:

Navigate to Looker Admin

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

Edit API keys

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

Create new API credentials

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

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 Type	Example
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 Automations

Add a Looker query task to your automation:

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.

Get started

Data Infrastructure

World Model

Agentic Intelligence

SDK

Automations

Data Apps

Integrations

Edge fleet

Manage

Workspaces

Authentication

Observability

Enterprise

Reference

REST API

Resources

Troubleshooting

Looker

Looker Integration

Prerequisites

Configuration

Configuration Options

Authentication

Metadata Synchronization

Sync Commands

How Metadata Storage Works

Overlay Metadata Example

Using Looker in Agents

Looker Filter Syntax

Using Looker in Automations

Query Parameters

CLI Commands

Test Connection

List Synced Explores

Troubleshooting

​Looker Integration

​Prerequisites

​Configuration

​Configuration Options

​Authentication

​Metadata Synchronization

​Sync Commands

​How Metadata Storage Works

​Overlay Metadata Example

​Using Looker in Agents

​Looker Filter Syntax

​Using Looker in Automations

​Query Parameters

​CLI Commands

​Test Connection

​List Synced Explores

​Troubleshooting

Looker Integration

Prerequisites

Configuration

Configuration Options

Authentication

Metadata Synchronization

Sync Commands

How Metadata Storage Works

Overlay Metadata Example

Using Looker in Agents

Looker Filter Syntax

Using Looker in Automations

Query Parameters

CLI Commands

Test Connection

List Synced Explores

Troubleshooting