개요

CAP Node.js에서 cds.ql 모듈은 CQN(Core Query Notation)으로 데이터베이스 쿼리를 작성하는 API를 제공합니다. SQL을 직접 쓰지 않고 SELECT, INSERT, UPDATE, DELETE 빌더를 사용하면 데이터베이스 종류(SQLite/HANA)에 상관없이 동일한 코드로 동작합니다.

핵심 개념

• CQN — CDS Query Notation. SQL과 유사하지만 CDS 모델 기반으로 동작하는 쿼리 표기법입니다.
• cds.ql 글로벌 객체 — SELECT, INSERT, UPSERT, UPDATE, DELETE가 전역으로 제공됩니다.
• 실행 방법 — await cds.run(query) 또는 await query (자동으로 cds.db.run에 전달)

코드 예제

const cds = require('@sap/cds');
const { Books, Authors } = cds.entities('bookshop');

// SELECT — 조건 필터링 + 정렬 + 페이지네이션
const books = await SELECT.from(Books)
  .where({ genre: 'Fiction', stock: { '>': 0 } })
  .orderBy('price desc')
  .limit(20, 40);  // top=20, skip=40

// SELECT — 특정 컬럼 + Association 확장
const withAuthor = await SELECT.from(Books)
  .columns('title', 'price', 'author.name as authorName');

// INSERT — 단일/다건 삽입
await INSERT.into(Books).entries(
  { title: 'CAP 입문', price: 29.99, stock: 100 },
  { title: 'CDS 마스터', price: 39.99, stock: 50 }
);

// UPSERT — 있으면 UPDATE, 없으면 INSERT
await UPSERT.into(Books).entries({ ID: 'abc-123', stock: 200 });

// UPDATE — 조건부 수정
await UPDATE(Books).set({ stock: { '-=': 1 } }).where({ ID: bookId });

// DELETE — 조건부 삭제
await DELETE.from(Books).where({ stock: 0 });

실무 팁

• await 직접 사용 — const result = await SELECT.from(Books)처럼 쿼리 객체를 직접 await하면 cds.db.run()이 자동 호출됩니다.
• 트랜잭션 — 이벤트 핸들러 내에서 실행되는 쿼리는 자동으로 같은 트랜잭션에 포함됩니다. 별도 트랜잭션이 필요하면 cds.tx()를 사용하세요.
• SQL 주입 방지 — CQN은 파라미터화된 쿼리로 변환되므로 SQL 주입에 안전합니다. 문자열 연결로 쿼리를 만들지 마세요.

더 읽어볼 자료

• CAP 공식: Querying in JavaScript — cds.ql API
• CAP 공식: Query Notation (CQN) 스펙
• SAP Community: Understanding CQL Queries (Node.js)
• SAP Community: Getting started with cds.ql — 101
• GitHub: SAP CAP Samples