> For the complete documentation index, see [llms.txt](https://documentation.kodiak.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.kodiak.finance/developers/kodiak-islands/subgraph/query-guide.md).

# Query Guide

### Introduction

This guide provides examples and best practices for querying the Kodiak Islands subgraph using GraphQL. Whether you're building a dashboard, analysis tool, or integrating with another application, these queries will help you extract the data you need.

#### Getting Started

To query the Kodiak Islands subgraph, you'll need to:

1. Know the subgraph endpoint URL ([sugraph-endpoint](https://api.goldsky.com/api/public/project_clpx84oel0al201r78jsl0r3i/subgraphs/kodiak-v3-berachain-mainnet/latest/gn))
2. Have a basic understanding of GraphQL query syntax
3. Use a GraphQL client (like Apollo Client) or make HTTP requests to the endpoint

#### Basic Query Structure

All GraphQL queries for the Kodiak Islands subgraph follow this basic structure:

```graphql
query {
  entity(where: { filter conditions }) {
    field1
    field2
    nestedEntity {
      nestedField1
      nestedField2
    }
  }
}
```

#### Common Query Examples

**1. Protocol Overview**

Get basic information about the protocol:

```graphql
query {
  kodiakIslandProtocols {
    id
    totalValueLockedUSD
    cumulativeTotalFeesUSD
    totalPoolCount
  }
}
```

**2. List All Vaults**

Retrieve all vaults with basic information:

```graphql
query {
  kodiakVaults(first: 100) {
    id
    name
    symbol
    totalValueLockedUSD
    inputToken {
      id
      symbol
      decimals
    }
    outputToken {
      id
      symbol
      decimals
    }
    manager
    managerFee
    createdTimestamp
  }
}
```

**3. Get Vault Details**

Get detailed information about a specific vault:

```graphql
query {
  kodiakVault(id: "0x1234567890abcdef1234567890abcdef12345678") {
    id
    name
    symbol
    totalValueLockedUSD
    cumulativeTotalFeesUSD
    cumulativeLpFeesUSD
    cumulativeManagerFeesUSD
    inputTokenBalance
    outputTokenSupply
    pricePerShare
    volumeUSD
    weeklyVolumeUSD
    weeklyFeesEarnedUSD
    lowerTick
    upperTick
    apr {
      averageApr
    }
    _token0 {
      symbol
    }
    _token1 {
      symbol
    }
    _token0Amount
    _token1Amount
    _token0AmountUSD
    _token1AmountUSD
  }
}
```

**4. Recent Deposits**

Query recent deposit events for a specific vault:

```graphql
query {
  kodiakDeposits(
    first: 10
    orderBy: timestamp
    orderDirection: desc
    where: { vault: "0x1234567890abcdef1234567890abcdef12345678" }
  ) {
    id
    timestamp
    from
    amount
    amountUSD
    amount0
    amount1
  }
}
```

**5. Recent Withdrawals**

Query recent withdrawal events for a specific vault:

```graphql
query {
  kodiakWithdraws(
    first: 10
    orderBy: timestamp
    orderDirection: desc
    where: { vault: "0x1234567890abcdef1234567890abcdef12345678" }
  ) {
    id
    timestamp
    to
    amount
    amountUSD
  }
}
```

**6. Daily Vault Performance**

Query daily snapshots for a vault to analyze performance over time:

```graphql
query {
  kodiakVaultDailySnapshots(
    first: 30
    orderBy: timestamp
    orderDirection: desc
    where: { vault: "0x1234567890abcdef1234567890abcdef12345678" }
  ) {
    id
    timestamp
    totalValueLockedUSD
    dailyTotalFeesUSD
    dailyLpFeesUSD
    dailyManagerFeesUSD
    volumeUSD
    volumeToken0
    volumeToken1
    apr
    pricePerShare
    lowerTick
    upperTick
  }
}
```

**7. Protocol Usage Metrics**

Query daily protocol usage metrics:

```graphql
query {
  kodiakUsageMetricsDailySnapshots(
    first: 30
    orderBy: timestamp
    orderDirection: desc
  ) {
    id
    timestamp
    dailyActiveUsers
    cumulativeUniqueUsers
    dailyTransactionCount
    dailyDepositCount
    dailyWithdrawCount
    totalPoolCount
  }
}
```

**8. Protocol Financial Metrics**

Query daily protocol financial metrics:

```graphql
query {
  kodiakFinancialsDailySnapshots(
    first: 30
    orderBy: timestamp
    orderDirection: desc
  ) {
    id
    timestamp
    totalValueLockedUSD
    dailyLpFeesUSD
    dailyManagerFeesUSD
    dailyTotalFeesUSD
  }
}
```

**9. Strategy Changes**

Track strategy changes for a specific vault:

```graphql
query {
  kodiakStrategyChanges(
    first: 20
    orderBy: timestamp
    orderDirection: desc
    where: { vault: "0x1234567890abcdef1234567890abcdef12345678" }
  ) {
    id
    timestamp
    lowerTick
    upperTick
  }
}
```

**10. Vault APR History**

Query APR history for a vault:

```graphql
query {
  kodiakVaultDailySnapshots(
    first: 90
    orderBy: timestamp
    orderDirection: desc
    where: { vault: "0x1234567890abcdef1234567890abcdef12345678" }
  ) {
    timestamp
    apr
  }
}
```

#### Filtering and Sorting

**Time-Based Filtering**

Filter snapshots within a specific time range:

```graphql
query {
  kodiakVaultDailySnapshots(
    where: {
      timestamp_gte: "1640995200" # Jan 1, 2022
      timestamp_lt: "1672531200"  # Jan 1, 2023
    }
  ) {
    timestamp
    totalValueLockedUSD
    dailyTotalFeesUSD
  }
}
```

**Value-Based Filtering**

Filter vaults by TVL:

```graphql
query {
  kodiakVaults(
    where: {
      totalValueLockedUSD_gt: "1000000" # > $1M TVL
    }
  ) {
    id
    name
    totalValueLockedUSD
  }
}
```

**Sorting Results**

Sort vaults by TVL in descending order:

```graphql
query {
  kodiakVaults(
    orderBy: totalValueLockedUSD
    orderDirection: desc
  ) {
    id
    name
    totalValueLockedUSD
  }
}
```

#### Pagination

For large result sets, use pagination with `first` and `skip`:

```graphql
query {
  kodiakVaults(
    first: 20  # Get 20 records
    skip: 20   # Skip first 20 records (for page 2)
    orderBy: totalValueLockedUSD
    orderDirection: desc
  ) {
    id
    name
    totalValueLockedUSD
  }
}
```

#### Advanced Queries

**Get User Activity Across Vaults**

Find all deposits and withdrawals for a specific user:

```graphql
query {
  deposits: kodiakDeposits(
    where: { from: "0xuser_address_here" }
  ) {
    timestamp
    vault {
      id
      name
    }
    amountUSD
  }
  withdraws: kodiakWithdraws(
    where: { to: "0xuser_address_here" }
  ) {
    timestamp
    vault {
      id
      name
    }
    amountUSD
  }
}
```

**Compare Multiple Vaults**

Compare performance metrics for multiple vaults:

```graphql
query {
  vault1: kodiakVault(id: "0xvault1_address_here") {
    id
    name
    totalValueLockedUSD
    weeklyFeesEarnedUSD
    apr {
      averageApr
    }
  }
  vault2: kodiakVault(id: "0xvault2_address_here") {
    id
    name
    totalValueLockedUSD
    weeklyFeesEarnedUSD
    apr {
      averageApr
    }
  }
}
```

#### Best Practices

1. **Query Only What You Need**: Only request the fields you actually need to minimize response size.
2. **Use Pagination**: For large collections, always use pagination to prevent timeouts.
3. **Filter Efficiently**: Apply filters at the query level rather than filtering results in your application.
4. **Optimize Sorting**: Sort at the query level for better performance.
5. **Cache Results**: GraphQL responses are highly cacheable. Implement client-side caching for better performance.
6. **Handle Time Data Correctly**: Remember that timestamps are in seconds since Unix epoch.

#### Error Handling

The subgraph may return errors for various reasons:

* Invalid query syntax
* Non-existent entities or fields
* Server timeouts for complex queries

Always implement proper error handling in your application to handle these cases gracefully.

#### Real-World Use Cases

**Building a Dashboard**

For a vault performance dashboard, you might combine protocol metrics with vault-specific data:

```graphql
query DashboardData {
  protocol: kodiakIslandProtocols(first: 1) {
    totalValueLockedUSD
    totalPoolCount
  }
  vaults: kodiakVaults(
    first: 10
    orderBy: totalValueLockedUSD
    orderDirection: desc
  ) {
    id
    name
    totalValueLockedUSD
    apr {
      averageApr
    }
  }
  recentActivity: kodiakDeposits(
    first: 5
    orderBy: timestamp
    orderDirection: desc
  ) {
    timestamp
    vault {
      name
    }
    amountUSD
  }
}
```

**Historical Analysis**

For analyzing a vault's performance over time:

```graphql
query VaultHistoricalAnalysis($vaultId: ID!, $days: Int!) {
  dailySnapshots: kodiakVaultDailySnapshots(
    first: $days
    orderBy: timestamp
    orderDirection: desc
    where: { vault: $vaultId }
  ) {
    timestamp
    totalValueLockedUSD
    dailyTotalFeesUSD
    dailyLpFeesUSD
    dailyManagerFeesUSD
    volumeUSD
    apr
  }
}
```

With these query examples and best practices, you should be well-equipped to extract valuable data from the Kodiak Islands subgraph for your applications.