# Query Guide

### Introduction

This guide covers common query patterns, optimization techniques, and best practices for retrieving data from the Panda Protocol subgraph.

### Basic Queries

#### Pool Data

```graphql
# Get basic pool information
{
  pandaPool(id: "0x123...") {
    id
    price
    volumeUSD
    swapsCount
    graduated
  }
}

# List active pools with high volume
{
  pandaPools(
    where: {
      volumeUSD_gt: "100000",
      graduated: false
    }
    orderBy: volumeUSD
    orderDirection: desc
    first: 10
  ) {
    id
    price
    volumeUSD
  }
}
```

#### Trading Activity

```graphql
# Recent swaps for a pool
{
  pandaPoolSwaps(
    where: { pool: "0x123..." }
    orderBy: timestamp
    orderDirection: desc
    first: 100
  ) {
    timestamp
    amountPandaIn
    amountPandaOut
    volumeUSD
    averagePrice
  }
}
```

### Advanced Queries

#### Time-Based Queries

```graphql
# Get pools with recent activity
{
  pandaPools(
    where: {
      lastSwapTimestamp_gt: "1634567890"
    }
  ) {
    id
    price
    lastSwapTimestamp
  }
}

# Get hourly price data
{
  priceSnapshots(
    where: {
      pool: "0x123...",
      timeframe: HOUR,
      timestamp_gt: "1634567890"
    }
    orderBy: timestamp
    orderDirection: asc
  ) {
    timestamp
    open
    high
    low
    close
  }
}
```

#### Market Analysis

```graphql
# Top pools by volume
{
  pandaPools(
    orderBy: volumeUSD
    orderDirection: desc
    first: 5
  ) {
    id
    volumeUSD
    marketCapUSD
    swapsCount
  }
}

# Token holder distribution
{
  token(id: "0x123...") {
    symbol
    holdersCount
    holders(
      orderBy: balance
      orderDirection: desc
      first: 10
    ) {
      address
      balance
      sharePercentage
    }
  }
}
```

### Query Optimization

#### Pagination

```graphql
# Using skip/first for pagination
{
  pandaPoolSwaps(
    skip: 100    # Skip first 100 results
    first: 50    # Get next 50 results
    orderBy: timestamp
    orderDirection: desc
  ) {
    id
    timestamp
  }
}
```

#### Field Selection

```graphql
# Good: Specific fields
{
  pandaPools {
    id
    price
    volumeUSD
  }
}

# Bad: Overfetching
{
  pandaPools {
    id
    price
    volumeUSD
    swapsCount
    lastSwapTimestamp
    graduated
    raised
    # ... unnecessary fields
  }
}
```

#### Using Fragments

```graphql
# Define reusable fragments
fragment PoolBasics on PandaPool {
  id
  price
  volumeUSD
  swapsCount
}

# Use in queries
{
  activePools: pandaPools(
    where: { graduated: false }
  ) {
    ...PoolBasics
  }
  
  graduatedPools: pandaPools(
    where: { graduated: true }
  ) {
    ...PoolBasics
  }
}
```

### Common Use Cases

#### Trading Interface Data

```graphql
# Get pool trading data
{
  pandaPool(id: "0x123...") {
    price
    pandaReserve
    baseReserve
    swapsCount
    lastSwapTimestamp
    recentSwaps: swaps(
      first: 50
      orderBy: timestamp
      orderDirection: desc
    ) {
      timestamp
      amountPandaIn
      amountPandaOut
      averagePrice
    }
  }
}
```

#### Analytics Dashboard

```graphql
# Get market overview
{
  statistics(id: "global") {
    totalVolumeUSD
    totalMarketCapUSD
    totalPandaPoolsCount
    totalGraduatedPandaPoolsCount
  }
  
  topPools: pandaPools(
    first: 5
    orderBy: volumeUSD
    orderDirection: desc
  ) {
    id
    volumeUSD
    marketCapUSD
    swapsCount
  }
}
```

### Real-time Data Updates

#### Polling Strategy

```graphql
# Efficient polling query
{
  pandaPool(id: "0x123...") {
    price
    lastSwapTimestamp
    pandaReserve
    baseReserve
  }
}
```

#### Using Block Numbers

```graphql
# Query at specific block
{
  pandaPool(id: "0x123...", block: { number: 15000000 }) {
    price
    volumeUSD
  }
}
```

### Error Handling

#### Null Checks

```graphql
# Handle potential null values
{
  pandaPool(id: "0x123...") {
    id # Will be null if pool doesn't exist
    price
    # Always check optional relationships
    swaps(first: 1) {
      id
    }
  }
}
```

#### Block Timestamps

```graphql
# Use block timestamps for time ranges
{
  pandaPoolSwaps(
    where: {
      timestamp_gt: "1634567890",
      timestamp_lt: "1634567990"
    }
  ) {
    timestamp
    averagePrice
  }
}
```

### Best Practices

1. **Query Performance**
   * Use pagination for large datasets
   * Select only needed fields
   * Optimize sorting and filtering
2. **Data Freshness**
   * Consider indexing delays
   * Implement proper polling intervals
   * Use block numbers for consistency
3. **Error Recovery**
   * Handle null entities gracefully
   * Validate data ranges
   * Implement retry logic

### Next Steps

Continue to Advanced Usage for:

* Complex query patterns
* Performance optimization
* Edge case handling