N+1 문제

N+1 쿼리 문제를 이해하고 Sonamu의 Subset과 Relation 기능으로 해결하는 방법을 다룹니다.

N+1 문제란?

N+1 문제는 1개의 메인 쿼리 후, N개의 추가 쿼리가 발생하는 성능 문제입니다.

문제 예시

// ❌ N+1 문제 발생
async function getUsersWithOrders() {
  // 1. 사용자 조회 (1번 쿼리)
  const users = await UserModel.getPuri().select("id", "name"); // 100명의 사용자

  // 2. 각 사용자의 주문 조회 (N번 쿼리)
  for (const user of users) {
    const orders = await OrderModel.getPuri().select("*").where({ user_id: user.id });

    user.orders = orders; // 100번 쿼리!
  }

  return users;
}

// 총 쿼리: 1 + 100 = 101번

성능 영향:

100명 사용자 → 101번 쿼리
1000명 사용자 → 1001번 쿼리
네트워크 왕복 시간 누적
데이터베이스 부하 증가

Sonamu의 해결 방법

Sonamu는 Subset을 통해 N+1 문제를 자동으로 해결합니다.

1. Subset 정의

Entity에서 Subset을 정의합니다:

// user.entity.json
{
  "name": "User",
  "properties": [
    {
      "name": "id",
      "type": "int",
      "isPrimary": true
    },
    {
      "name": "name",
      "type": "varchar"
    }
  ],
  "subsets": {
    "A": {
      "fields": ["id", "name"]
    },
    "WithOrders": {
      "fields": ["id", "name"],
      "relations": [
        {
          "name": "orders",
          "subset": "A"
        }
      ]
    }
  }
}

2. Subset 사용

// ✅ Subset으로 N+1 해결
async function getUsersWithOrders() {
  // getSubsetQueries로 쿼리 빌더 얻기
  const { qb } = UserModel.getSubsetQueries("WithOrders");

  // 자동으로 최적화된 쿼리 실행
  const result = await UserModel.executeSubsetQuery({
    subset: "WithOrders",
    qb,
    params: { num: 100, page: 1 },
  });

  // result.rows[0].orders는 이미 로드됨
  // 추가 쿼리 없음!

  return result.rows;
}

// 총 쿼리: 2번 (users 1번 + orders 1번)

내부 동작:

사용자 조회 (1번)
모든 사용자 ID로 주문 일괄 조회 (1번)
메모리에서 조인

Subset 활용 패턴

단일 Relation

// post.entity.json
{
  "name": "Post",
  "subsets": {
    "WithAuthor": {
      "fields": ["id", "title", "content"],
      "relations": [
        {
          "name": "author",
          "subset": "A"
        }
      ]
    }
  }
}

// 게시글과 작성자 조회
const { qb } = PostModel.getSubsetQueries("WithAuthor");
const result = await PostModel.executeSubsetQuery({
  subset: "WithAuthor",
  qb,
  params: { num: 20, page: 1 },
});

result.rows.forEach((post) => {
  console.log(`${post.title} by ${post.author.name}`);
});

다중 Relations

// order.entity.json
{
  "name": "Order",
  "subsets": {
    "Detail": {
      "fields": ["id", "total", "status"],
      "relations": [
        {
          "name": "user",
          "subset": "A"
        },
        {
          "name": "items",
          "subset": "A"
        },
        {
          "name": "payment",
          "subset": "A"
        }
      ]
    }
  }
}

// 주문 + 사용자 + 아이템 + 결제 정보
const { qb } = OrderModel.getSubsetQueries("Detail");
const result = await OrderModel.executeSubsetQuery({
  subset: "Detail",
  qb: qb.where({ status: "completed" }),
  params: { num: 20, page: 1 },
});

// 모든 관계가 이미 로드됨
result.rows.forEach((order) => {
  console.log(`Order ${order.id}`);
  console.log(`User: ${order.user.name}`);
  console.log(`Items: ${order.items.length}`);
  console.log(`Payment: ${order.payment.method}`);
});

중첩 Relations

// comment.entity.json
{
  "name": "Comment",
  "subsets": {
    "WithAll": {
      "fields": ["id", "content", "created_at"],
      "relations": [
        {
          "name": "author",
          "subset": "A"
        },
        {
          "name": "post",
          "subset": "WithAuthor" // 중첩: 게시글 + 게시글 작성자
        }
      ]
    }
  }
}

// 댓글 + 댓글 작성자 + 게시글 + 게시글 작성자
const { qb } = CommentModel.getSubsetQueries("WithAll");
const result = await CommentModel.executeSubsetQuery({
  subset: "WithAll",
  qb,
  params: { num: 20, page: 1 },
});

result.rows.forEach((comment) => {
  console.log(`${comment.author.name}: ${comment.content}`);
  console.log(`  on "${comment.post.title}" by ${comment.post.author.name}`);
});

// 쿼리 4번만 실행:
// 1. comments
// 2. comment authors
// 3. posts
// 4. post authors

whereIn을 활용한 수동 해결

Subset이 없는 경우 whereIn으로 최적화할 수 있습니다:

// ❌ N+1 문제
async function getUsersWithOrders() {
  const users = await UserModel.getPuri().select("id", "name");

  for (const user of users) {
    user.orders = await OrderModel.getPuri().select("*").where({ user_id: user.id });
  }

  return users;
}

// ✅ whereIn으로 최적화
async function getUsersWithOrders() {
  // 1. 사용자 조회
  const users = await UserModel.getPuri().select("id", "name");

  const userIds = users.map((u) => u.id);

  // 2. 모든 주문 한 번에 조회
  const orders = await OrderModel.getPuri().select("*").whereIn("user_id", userIds);

  // 3. 메모리에서 매핑
  const ordersByUserId = orders.reduce(
    (acc, order) => {
      if (!acc[order.user_id]) acc[order.user_id] = [];
      acc[order.user_id].push(order);
      return acc;
    },
    {} as Record<number, Order[]>,
  );

  users.forEach((user) => {
    user.orders = ordersByUserId[user.id] || [];
  });

  return users;
}

// 쿼리 2번: users + orders

DataLoader 패턴

반복적인 조회가 필요한 경우 DataLoader 패턴을 사용합니다:

class OrderModelClass extends BaseModelClass {
  // 사용자별 주문 로더
  private userOrdersLoader = new DataLoader(async (userIds: number[]) => {
    const orders = await this.getPuri().select("*").whereIn("user_id", userIds);

    // user_id별로 그룹화
    const grouped = userIds.map((userId) => orders.filter((o) => o.user_id === userId));

    return grouped;
  });

  async getOrdersByUserId(userId: number): Promise<Order[]> {
    return this.userOrdersLoader.load(userId);
  }
}

// 사용
async function processUsers(users: User[]) {
  for (const user of users) {
    // DataLoader가 자동으로 배치 처리
    const orders = await OrderModel.getOrdersByUserId(user.id);
    console.log(`${user.name}: ${orders.length} orders`);
  }
}

// 내부적으로 whereIn으로 한 번에 조회

실전 예제

API 엔드포인트 최적화

class PostModelClass extends BaseModelClass {
  // ❌ N+1 발생
  @api({ httpMethod: "GET" })
  async listPostsSlow() {
    const posts = await this.getPuri().select("id", "title", "content");

    // N+1 발생!
    for (const post of posts) {
      post.author = await UserModel.findById(post.author_id);
      post.comments = await CommentModel.getPuri().where({ post_id: post.id });
    }

    return posts;
  }

  // ✅ Subset으로 최적화
  @api({ httpMethod: "GET" })
  async listPostsFast() {
    const { qb } = this.getSubsetQueries("WithAuthorAndComments");

    return this.executeSubsetQuery({
      subset: "WithAuthorAndComments",
      qb: qb.orderBy("created_at", "desc"),
      params: { num: 20, page: 1 },
    });
  }
}

대시보드 데이터

class DashboardService {
  // ❌ N+1 발생
  async getDashboardSlow() {
    const users = await UserModel.getPuri().select("id", "name");

    const stats = [];
    for (const user of users) {
      const orderCount = await OrderModel.getPuri()
        .select({ count: Puri.count() })
        .where({ user_id: user.id });

      const totalSpent = await OrderModel.getPuri()
        .select({ total: Puri.sum("total") })
        .where({ user_id: user.id });

      stats.push({
        user: user.name,
        orderCount: orderCount[0].count,
        totalSpent: totalSpent[0].total,
      });
    }

    return stats;
  }

  // ✅ JOIN으로 최적화
  async getDashboardFast() {
    return UserModel.getPuri()
      .select(
        "users.id",
        "users.name",
        knex.raw("COUNT(orders.id) as order_count"),
        knex.raw("COALESCE(SUM(orders.total), 0) as total_spent"),
      )
      .leftJoin("orders", "orders.user_id", "users.id")
      .groupBy("users.id");
  }
}

N+1 감지하기

쿼리 로깅

// sonamu.config.ts
export default {
  database: {
    defaultOptions: {
      debug: true, // 모든 쿼리 출력
    },
  },
} satisfies SonamuConfig;

실행 후 콘솔을 확인하세요:

SELECT * FROM users;
SELECT * FROM orders WHERE user_id = 1;
SELECT * FROM orders WHERE user_id = 2;
SELECT * FROM orders WHERE user_id = 3;
...

반복적인 비슷한 쿼리가 보이면 N+1 문제입니다!

테스트로 감지

test("N+1 문제 확인", async () => {
  // 쿼리 카운터
  let queryCount = 0;

  const db = UserModel.getPuri().getDB();
  db.on("query", () => queryCount++);

  // 테스트
  const { qb } = UserModel.getSubsetQueries("WithOrders");
  const result = await UserModel.executeSubsetQuery({
    subset: "WithOrders",
    qb: qb.limit(10),
    params: { num: 10, page: 1 },
  });

  // 쿼리 수 검증
  expect(queryCount).toBeLessThan(5); // N+1이면 11번 이상
  expect(result.rows).toHaveLength(10);
});

성능 비교

N+1 문제가 있는 경우

100명 사용자 조회:
- 쿼리: 101번
- 시간: ~2000ms
- DB 커넥션: 101번 획득/반환

Subset으로 최적화한 경우

100명 사용자 조회:
- 쿼리: 2번
- 시간: ~50ms
- DB 커넥션: 2번 획득/반환

40배 이상 성능 향상!

Best Practices

1. 항상 Subset 먼저 고려

// ✅ Subset 사용
const { qb } = PostModel.getSubsetQueries("WithAuthor");
const result = await PostModel.executeSubsetQuery({
  subset: "WithAuthor",
  qb,
  params: { num: 20, page: 1 },
});

// ❌ 수동 로딩
const posts = await PostModel.getPuri();
for (const post of posts) {
  post.author = await UserModel.findById(post.author_id);
}

2. API 응답에는 필요한 Subset 정의

{
  "name": "User",
  "subsets": {
    "ForAPI": {
      "fields": ["id", "name", "email"],
      "relations": [
        {
          "name": "profile",
          "subset": "Public"
        }
      ]
    }
  }
}

3. 복잡한 쿼리는 JOIN 고려

// Subset보다 JOIN이 나은 경우:
// - 집계 함수 필요
// - 복잡한 필터링
// - 대량 데이터

4. 개발 중 쿼리 모니터링

// 개발 환경에서만 쿼리 로깅
export default {
  database: {
    defaultOptions: {
      debug: process.env.NODE_ENV === "development",
    },
  },
} satisfies SonamuConfig;

체크리스트

N+1 문제를 방지하려면:

반복문 안에서 DB 조회하지 않기
Subset으로 관계 데이터 미리 로드
whereIn으로 일괄 조회
JOIN을 활용한 집계
개발 중 쿼리 로깅 활성화
테스트로 쿼리 수 검증
API 응답 시간 모니터링

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

N+1 문제란?

문제 예시

Sonamu의 해결 방법

1. Subset 정의

2. Subset 사용

Subset 활용 패턴

단일 Relation

다중 Relations

중첩 Relations

whereIn을 활용한 수동 해결

DataLoader 패턴

실전 예제

API 엔드포인트 최적화

대시보드 데이터

N+1 감지하기

쿼리 로깅

테스트로 감지

성능 비교

N+1 문제가 있는 경우

Subset으로 최적화한 경우

Best Practices

1. 항상 Subset 먼저 고려

2. API 응답에는 필요한 Subset 정의

3. 복잡한 쿼리는 JOIN 고려

4. 개발 중 쿼리 모니터링

체크리스트

관련 문서

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

​N+1 문제란?

​문제 예시

​Sonamu의 해결 방법

​1. Subset 정의

​2. Subset 사용

​Subset 활용 패턴

​단일 Relation

​다중 Relations

​중첩 Relations

​whereIn을 활용한 수동 해결

​DataLoader 패턴

​실전 예제

​API 엔드포인트 최적화

​대시보드 데이터

​N+1 감지하기

​쿼리 로깅

​테스트로 감지

​성능 비교

​N+1 문제가 있는 경우

​Subset으로 최적화한 경우

​Best Practices

​1. 항상 Subset 먼저 고려

​2. API 응답에는 필요한 Subset 정의

​3. 복잡한 쿼리는 JOIN 고려

​4. 개발 중 쿼리 모니터링

​체크리스트

​관련 문서

N+1 문제란?

문제 예시

Sonamu의 해결 방법

1. Subset 정의

2. Subset 사용

Subset 활용 패턴

단일 Relation

다중 Relations

중첩 Relations

whereIn을 활용한 수동 해결

DataLoader 패턴

실전 예제

API 엔드포인트 최적화

대시보드 데이터

N+1 감지하기

쿼리 로깅

테스트로 감지

성능 비교

N+1 문제가 있는 경우

Subset으로 최적화한 경우

Best Practices

1. 항상 Subset 먼저 고려

2. API 응답에는 필요한 Subset 정의

3. 복잡한 쿼리는 JOIN 고려

4. 개발 중 쿼리 모니터링

체크리스트

관련 문서