> ## Documentation Index
> Fetch the complete documentation index at: https://oxy.tech/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Looker

> Connect Oxygen to Looker for querying explores and syncing metadata

<RewriteBanner />

# Looker Integration

Oxygen integrates with [Looker](https://cloud.google.com/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`:

```yaml theme={null}
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:

```bash theme={null}
export LOOKER_CLIENT_ID="your_client_id"
export LOOKER_CLIENT_SECRET="your_client_secret"
```

To generate API credentials in Looker:

<Steps>
  <Step title="Navigate to Looker Admin">
    Go to your Looker instance and navigate to **Admin > Users**.
  </Step>

  <Step title="Edit API keys">
    Select your user (or a service account) and click **Edit Keys** under the API section.
  </Step>

  <Step title="Create new API credentials">
    Click **New API Key**. Copy the **Client ID** and **Client Secret** — the secret is only shown once.
  </Step>

  <Step title="Set environment variables">
    Export the credentials in your shell or add them to your `.env` file:

    ```bash theme={null}
    export LOOKER_CLIENT_ID="your_client_id"
    export LOOKER_CLIENT_SECRET="your_client_secret"
    ```
  </Step>
</Steps>

## 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

```bash theme={null}
# 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

```yaml theme={null}
# 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:

```yaml theme={null}
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:

```yaml theme={null}
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

```bash theme={null}
oxy looker test --integration my_looker
```

### List Synced Explores

```bash theme={null}
# 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.