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

# Explorer Tools

> Query historical blockchain data using SQL and saved queries.

## Overview

Explorer tools allow your AI agents to query Allium's historical blockchain data using SQL queries. These tools provide access to raw and decoded data across 80+ blockchains.

## Available Tools

| Tool Name                 | Description                                                                           |
| :------------------------ | :------------------------------------------------------------------------------------ |
| `explorer_create_query`   | Create a new saved query programmatically. Returns a `query_id` for future use        |
| `explorer_update_query`   | Update an existing saved query's SQL, parameters, or configuration                    |
| `explorer_run_query`      | Run a saved Explorer query using its `query_id`. Supports parameterization            |
| `explorer_run_sql`        | Run raw SQL directly against Allium's production datasets                             |
| `explorer_search_schemas` | Semantic search across all schema docs. Returns relevant table IDs                    |
| `explorer_browse_schemas` | Browse data schema hierarchy like a filesystem to discover databases, schemas, tables |
| `explorer_fetch_schema`   | Fetch YAML schema metadata by table IDs (full table name, e.g. `ethereum.raw.blocks`) |

<Info>
  Schema IDs match full table names (e.g. `ethereum.raw.token_transfers`). Use search before fetching.
</Info>

## Tool Usage

### Create & Manage Queries

#### Create a New Query

Save a query programmatically for later reuse:

```json theme={null}
{
  "name": "explorer_create_query",
  "arguments": {
    "title": "Ethereum Transactions by Date",
    "sql": "SELECT * FROM ethereum.raw.transactions WHERE block_timestamp > {{start_date}} LIMIT {{limit}}",
    "limit": 1000,
    "parameters": {
      "start_date": "2024-01-01",
      "limit": "1000"
    }
  }
}
```

**Returns:**

```json theme={null}
{
  "query_id": "abc123..."
}
```

Save this `query_id` to run or update the query later.

#### Update an Existing Query

Modify a saved query's SQL or configuration:

```json theme={null}
{
  "name": "explorer_update_query",
  "arguments": {
    "query_id": "abc123...",
    "title": "Ethereum Transactions by Date (Updated)",
    "sql": "SELECT block_number, hash, value FROM ethereum.raw.transactions WHERE block_timestamp > {{start_date}}",
    "limit": 5000
  }
}
```

**Common use cases:**

* Optimize SQL for better performance
* Adjust row limits
* Update parameter defaults
* Change compute profiles

### Run Saved Queries

Execute queries created in the Allium App or via `explorer_create_query`.

<Steps>
  <Step title="Get a Query ID">
    Create a query using `explorer_create_query` or save one in the Allium App to obtain its `query_id`.
  </Step>

  <Step title="Call the Tool">
    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "tools/call",
      "params": {
        "name": "explorer_run_query",
        "arguments": {
          "query_id": "<YOUR_QUERY_ID>"
          // "parameters": { "param": "value" } // optional
        }
      }
    }
    ```
  </Step>
</Steps>

**Response includes:**

* `sql` - Full query text
* `data` - Result rows
* `meta.columns` - Column names and types
* `queried_at` - Execution timestamp

### Run Raw SQL

Execute ad-hoc SQL queries directly:

```json theme={null}
{
  "name": "explorer_run_sql",
  "arguments": {
    "sql": "SELECT COUNT(*) FROM ethereum.raw.transactions"
  }
}
```

<Note>
  Supports up to **250,000 rows** per query by default.
</Note>

### Explore Schemas

<Tabs>
  <Tab title="Search Schemas">
    Find relevant tables using semantic search:

    ```json theme={null}
    {
      "name": "explorer_search_schemas",
      "arguments": {
        "query": "erc20 token transfers"
      }
    }
    ```

    **Returns:**

    ```json theme={null}
    ["ethereum.raw.token_transfers", "ethereum.unified.transfers", ...]
    ```
  </Tab>

  <Tab title="Browse Schemas">
    Navigate the schema hierarchy like a filesystem:

    ```json theme={null}
    {
      "name": "explorer_browse_schemas",
      "arguments": {
        "path": ""  // Empty = list all databases
      }
    }
    ```

    **Navigation paths:**

    * `""` or `"."` → List all databases (ethereum, solana, bitcoin, etc.)
    * `"ethereum"` → List schemas in ethereum database (raw, decoded, etc.)
    * `"ethereum.raw"` → List tables in ethereum.raw schema
    * `"ethereum.raw.blocks"` → Get full table details with columns

    **Use cases:**

    * Discover available databases and schemas
    * Explore tables within a specific schema
    * Fetch complete table details for a known table
  </Tab>

  <Tab title="Fetch Schema">
    Retrieve a table's YAML schema metadata:

    ```json theme={null}
    {
      "name": "explorer_fetch_schema",
      "arguments": {
        "id": "ethereum.raw.token_transfers"
      }
    }
    ```

    **Returns:**

    ```yaml theme={null}
    table: ethereum.raw.token_transfers
    description: ERC20 token transfers on Ethereum mainnet
    columns:
      - name: transaction_hash
        type: STRING
        description: Transaction hash
      - name: amount
        type: NUMBER
        description: Raw token amount (unadjusted)
      ...
    ```
  </Tab>
</Tabs>

## Response Format

All Explorer query tools return a JSON-RPC result:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": {
      "text": "{\"sql\": \"SELECT ...\", \"data\": [...], \"meta\": {\"columns\": [...]}, \"queried_at\": \"2025-07-01T00:00:00Z\"}"
    }
  }
}
```

Parse `content.text` as JSON to extract:

* **sql** - Full query string
* **data** - List of result rows (objects)
* **meta.columns** - Each column's name and data type
* **queried\_at** - ISO timestamp

## Related Resources

<CardGroup cols={2}>
  <Card title="Create Query API" icon="plus" href="/api/explorer/create-query">
    REST endpoint for creating queries
  </Card>

  <Card title="Update Query API" icon="pen" href="/api/explorer/update-query">
    REST endpoint for updating queries
  </Card>

  <Card title="Run Queries" icon="rotate" href="/app/run-queries">
    Learn how to save queries in Explorer
  </Card>

  <Card title="Data Catalog" icon="database" href="/historical-data/overview">
    Explore available data schemas
  </Card>

  <Card title="Explorer API" icon="code" href="/api/explorer/overview">
    REST endpoints for running queries
  </Card>
</CardGroup>