Cassandra 쿼리 언어

Cassandra 쿼리 언어 (CQL) v3.4.3 전체 참조 (Cassandra Query Language (CQL) v3.4.3)

이 문서는 Cassandra 쿼리 언어(CQL) 버전 3 전체를 하나로 묶은 참조 문서예요. CQL v3는 CQL v2와 하위 호환되지 않으며 여러 면에서 다릅니다. 각 문(stmt)의 세부 설명은 해당 개별 페이지(데이터 정의, 데이터 조작, 데이터 타입, 함수, 보안 등)에 분리되어 있으므로, 여기서는 문서의 전체 구조와 핵심 내용을 안내해요.

출처: 문서

본문

CQL 구문 (CQL Syntax)

서문 (Preamble)

이 문서는 Cassandra Query Language(CQL) 버전 3을 설명해요. CQL v3는 CQL v2와 하위 호환되지 않으며 수많은 방식으로 다릅니다. 이 문서는 언어의 마지막 버전을 설명하며, 변경 사항(changes) 섹션은 CQL v3의 각 버전 간 차이를 제공해요.

CQL v3는 데이터가 컬럼(columns) 의 행(rows) 을 포함하는 테이블(tables) 에 저장된다는 점에서 SQL과 매우 유사한 모델을 제공해요. 따라서 이 문서에서 사용될 때 이 용어들(테이블, 행, 컬럼)은 SQL에서와 같은 정의를 가져요. 다만 이것들은 Cassandra의 내부 구현과 thrift 및 CQL v2 API에 있는 행·컬럼 개념을 지칭하는 것이 아님을 유의하세요.

규약 (Conventions)

CQL 구문을 지정하기 위해 이 문서에서는 다음 규약을 사용해요:

• 언어 규칙은 BNF와 유사한 표기로 주어져요:

::= TERMINAL

• 비단말 기호는 <angle brackets>을 가져요.
• BNF에 대한 추가 축약 표기로, 전통적인 정규 표현식 기호(?, +, *)를 사용해 주어진 기호가 선택적이고/반복될 수 있음을 나타내요. 또한 기호를 그룹화하는 괄호와 <characters> 중 하나를 나타내는 [<characters>] 표기를 허용해요.
• 문법은 문서화 목적으로 제공되며 몇 가지 사소한 세부 사항은 생략해요.
• 샘플 코드는 코드 블록으로 제공돼요.
• 본문에서 키워드나 CQL 코드 조각에 대한 참조는 고정 폭 글꼴로 표시돼요.

식별자와 키워드 (Identifiers and keywords)

CQL 언어는 테이블, 컬럼 및 기타 객체를 식별하기 위해 식별자(identifiers) (또는 이름(names))를 사용해요. 식별자는 정규 표현식 ``[a-zA-Z0-9_]*과 일치하는 토큰이에요.

SELECT나 WITH 같은 많은 식별자는 키워드(keywords) 입니다. 그들은 언어에 대해 고정된 의미를 가지며 대부분 예약되어 있어요. 키워드 목록은 부록 A에서 찾을 수 있어요.

식별자와 (따옴표 없는) 키워드는 대소문자를 구분하지 않아요. 따라서 SELECT는 select나 sElEcT와 같고, myId는 myid나 MYID와 같아요. 흔히 사용되는 규약(특히 이 문서의 샘플)은 키워드에 대문자, 다른 식별자에 소문자를 사용하는 것이에요.

따옴표 식별자(quoted identifiers) 라는 두 번째 종류의 식별자가 있는데, 임의 문자 시퀀스를 큰따옴표(")로 감싸 정의돼요. 따옴표 식별자는 절대 키워드가 아니에요. 따라서 "select"는 예약 키워드가 아니며 컬럼을 참조하는 데 사용될 수 있는 반면, select는 파싱 오류를 발생시켜요. 또한 따옴표 식별자는 대소문자를 구분해요("My Quoted Id"는 "my quoted id"와 다름). [a-zA-Z0-9_]*과 일치하는 완전히 소문자인 따옴표 식별자는 큰따옴표를 제거해서 얻은 따옴표 없는 식별자와 동등해요("myid"는 myid및myId와 동등하지만 "myId"와는 다름). 따옴표 식별자 안에서 큰따옴표 문자는 반복해 이스케이프할 수 있으므로 "foo "" bar"`는 유효한 식별자예요.

경고 따옴표 식별자 는 임의의 이름을 가진 컬럼 선언을 허용하며, 이는 서버가 사용하는 특정 이름과 충돌할 수 있어요. 예를 들어 조건부 갱신을 사용할 때 서버는 "[applied]"라는 특별한 결과를 포함한 결과 집합으로 응답해요. 그러한 이름의 컬럼을 선언했다면 일부 도구를 혼란스럽게 할 수 있으므로 피해야 해요. 일반적으로 따옴표 없는 식별자를 선호해야 하지만, 따옴표 식별자를 사용한다면 "[applied]" 같은 대괄호로 감싼 이름과 "f(x)"처럼 함수 호출처럼 보이는 이름을 피하는 것이 강력히 권장돼요.

상수 (Constants)

CQL은 문자열, 정수, 부동소수점, 불리언, uuid, blob 다음 종류의 상수(constants) 를 정의해요:

• 문자열 상수는 작은따옴표(')로 감싼 임의 문자 시퀀스예요. 문자열에 작은따옴표를 포함하려면 반복하면 돼요(예: 'It''s raining today'). 이들은 큰따옴표를 사용하는 따옴표 식별자와 혼동하지 마세요.
• 정수 상수는 '-'?[0-9]+로 정의돼요.
• 부동소수점 상수는 '-'?[0-9]+('.'[0-9]*)?([eE][+-]?[0-9+])?로 정의돼요. 게다가 NaN과 Infinity도 부동소수점 상수예요.
• 불리언 상수는 대소문자 구분 없이 true 또는 false예요(즉 True도 유효한 불리언 상수).
• UUID 상수는 hex{8}-hex{4}-hex{4}-hex{4}-hex{12}로 정의되며, 여기서 hex는 16진 문자(예: [0-9a-fA-F])이고 {4}는 그러한 문자의 수예요.
• blob 상수는 0[xX](hex)+로 정의된 16진수예요.

이 상수들이 어떻게 타입화되는지는 데이터 타입 섹션을 참조하세요.

용어 (Terms)

CQL은 CQL이 지원하는 값의 종류를 나타내는 term 의 개념을 가져요. term은 다음과 같이 정의돼요:

term::= constant | literal | function_call | arithmetic_operation | type_hint | bind_marker
literal::= collection_literal | vector_literal | udt_literal | tuple_literal
function_call::= identifier '(' [ term (',' term)* ] ')'
arithmetic_operation::= '-' term | term ('+' | '-' | '*' | '/' | '%') term
type_hint::= '(' cql_type ')' term
bind_marker::= '?' | ':' identifier

따라서 term은 다음 중 하나예요:

• 상수
• 컬렉션, 벡터, 사용자 정의 타입 또는 튜플에 대한 리터럴
• 함수 호출
• term 간의 산술 연산
• 타입 힌트
• 실행 시점에 바인딩될 변수를 나타내는 바인드 마커(bind marker). 바인드 마커는 익명(?) 또는 명명(:some_name)일 수 있어요.

주석 (Comments)

CQL의 주석은 이중 대시(--) 또는 이중 슬래시(//)로 시작하는 줄이에요. 여러 줄 주석도 /*와 */로 감싸 지원되지만 중첩은 지원되지 않아요.

-- This is a comment
// This is a comment too
/* This is
a multi-line comment */

문 (Statements)

CQL은 문(statements)으로 구성돼요. SQL에서처럼 이 문들은 3가지 범주로 나눌 수 있어요:

• 데이터가 저장되는 방식을 설정·변경하는 데이터 정의(data definition) 문
• 데이터를 변경하는 데이터 조작(data manipulation) 문
• 데이터를 조회하는 쿼리(queries)

모든 문은 세미콜론(;)으로 끝나지만 단일 문을 다룰 때는 생략할 수 있어요.

잠깐 깊이 들어가기 전에 몇 가지 개념(바인드 변수, 프로퍼티, 테이블 이름, 문자열 리터럴)이 정의돼요. 문자열은 작은따옴표 또는 두 개의 달러 문자로 감쌀 수 있어요. 두 번째 구문은 작은따옴표를 포함하는 문자열을 허용하기 위해 도입되었으며, 대표적인 후보는 사용자 정의 함수의 소스 코드 조각이에요.

'some string value'
$$A King's ransom$$

준비된 문 (Prepared Statement)

CQL은 준비된 문(prepared statements) 을 지원해요. 준비된 문은 쿼리를 한 번만 파싱하고 다양한 구체 값으로 여러 번 실행할 수 있게 하는 최적화예요. 문에서 컬럼 값이 예상되는 곳마다 <variable>을 대신 사용할 수 있어요. 바인드 변수가 있는 문은 준비(prepare) 되어야 하며, 준비된 후 바인드 변수에 대한 구체 값을 제공해 실행할 수 있어요. 또한 바인드 마커는 LIMIT, TIMESTAMP, TTL 절의 값을 제공하는 데도 사용될 수 있어요.

준비된 문은 Caffeine 관리 캐시를 사용해 Cassandra에 의해 메모리에 캐시되며, 이는 prepared_statements_cache_size로 구성할 수 있어요. 캐시는 또한 system.prepared_statements 테이블에 영속화되어 시작 시 메모리에 미리 로드될 수 있어요. 최적 성능을 위해 CQL 문의 모든 비상수 값에 바인드 <variable>을 사용하는 것이 중요해요. 쿼리에 리터럴 값을 직접 포함하면 각 변형이 고유한 문으로 취급되어 별도로 준비·캐시되어야 하므로, 작게 설계된 캐시를 곧 넘치게 할 수 있어요.

데이터 정의 (Data Definition)

• CREATE KEYSPACE — 새 최상위 키스페이스 를 생성. 키스페이스는 테이블 집합에 대한 복제 전략과 옵션을 정의하는 네임스페이스예요. 지원 프로퍼티는 replication(필수, 'class' 하위 옵션 포함)과 durable_writes(기본 true). 기본 'class': 'SimpleStrategy'(전체 클러스터용 단순 복제 계수), 'NetworkTopologyStrategy'(데이터센터별 복제 계수).
• USE — 현재 키스페이스를 지정.
• ALTER KEYSPACE — 기존 키스페이스의 프로퍼티 변경.
• DROP KEYSPACE — 키스페이스와 포함된 모든 것을 즉시·비가역적으로 제거.
• CREATE TABLE — 새 테이블 생성. 각 테이블은 행 의 집합이며 이름, 컬럼, 옵션을 정의. CREATE COLUMNFAMILY는 CREATE TABLE의 별칭.
  • 각 행은 PRIMARY KEY로 고유 식별되며 반드시 하나 정의. 기본 키의 첫 컬럼은 파티션 키(partition key) — 같은 파티션 키를 공유하는 모든 행은 같은 물리 노드에 저장되고, 원자적·격리적으로 수행됨. 추가 괄호로 복합 파티션 키 정의 가능. 나머지 컬럼은 클러스터링 컬럼(clustering columns) — 주어진 파티션 키의 행은 클러스터링 순서대로 저장됨.
  • STATIC 컬럼은 같은 파티션의 모든 행이 공유. 제한: COMPACT STORAGE 테이블 불가, 클러스터링 컬럼 없는 테이블 불가, PRIMARY KEY가 아닌 컬럼만 가능.
  • 옵션: COMPACT STORAGE(CQL3 이전 정의와의 하위 호환 목적, 비권장), CLUSTERING ORDER(디스크 내 행 순서), comment, gc_grace_seconds(기본 864000), bloom_filter_fp_chance(기본 0.00075), default_time_to_live(기본 0), compaction, compression, caching, crc_check_chance(기본 1.0).
  • 컴팩션 옵션: 'class'(기본 'SizeTieredCompactionStrategy', 'LeveledCompactionStrategy', 'TimeWindowCompactionStrategy'), enabled, tombstone_threshold, tombstone_compaction_interval, unchecked_tombstone_compaction, min_sstable_size, min_threshold, max_threshold, bucket_low/bucket_high, sstable_size_in_mb, timestamp_resolution, compaction_window_unit/compaction_window_size, unsafe_aggressive_sstable_expiration.
  • 압축 옵션: class(기본 LZ4Compressor), enabled, chunk_length_in_kb(기본 64KB).
  • 캐싱 옵션: keys(기본 ALL), rows_per_partition(기본 NONE).
• ALTER TABLE — 컬럼 추가(ADD), 제거(DROP), 기본 키 컬럼 이름 변경(RENAME), 옵션 변경(WITH). 컴팩션/압축 하위 옵션 설정 시 이전 옵션이 모두 지워지므로 재지정 필요.
• CQL 타입 호환성(ALTER TABLE): 일반 컬럼은 다음만 변환 가능 — timestamp→bigint; ascii, bigint, boolean, date, decimal, double, float, inet, int, smallint, text, time, timestamp, timeuuid, tinyint, uuid, varchar, varint→blob; int→date; ascii, varchar→text; bigint→time; bigint→timestamp; timeuuid→uuid; ascii, text→varchar; bigint, int, timestamp→varint. 클러스터링 컬럼은 더 엄격함: ascii, text, varchar→blob; ascii, varchar→text; ascii, text→varchar.
• DROP TABLE — 테이블과 데이터를 즉시·비가역적으로 제거.
• TRUNCATE — 테이블에서 모든 데이터를 영구히 제거(테이블 자체는 유지).
• CREATE INDEX — 주어진 컬럼의 새 보조 색인 생성. USING으로 색인 타입 지정 가능 — 두 내장 타입: legacy_local_table(기본, 숨겨진 로컬 테이블로 구현)과 sai("storage-attached" 색인). 사용자 지정 색인은 정규화된 클래스 이름으로. 맵 컬럼 색인 시 keys() 함수 안에 배치하면 맵 키를 색인해 WHERE 절에서 CONTAINS KEY 사용 가능.
• DROP INDEX — 기존 보조 색인 제거(키스페이스 선택 지정 가능).
• CREATE MATERIALIZED VIEW — 기본 테이블(베이스 테이블)의 행에 대응하는 새 구체화 뷰 생성. WHERE 절은 뷰 기본 키 컬럼의 NULL을 금지하는 표현식을 포함해야 하며(IS NOT NULL), 기본 테이블 기본 키 컬럼만 IS NOT NULL 외의 표현식으로 제한 가능.
• ALTER MATERIALIZED VIEW — 옵션 갱신(CREATE TABLE 옵션과 동일). DROP MATERIALIZED VIEW — 기존 뷰 제거.
• CREATE TYPE / ALTER TYPE / DROP TYPE — 사용자 정의 타입(UDT) 생성·변경·제거. 타입 이름은 식별자이며 기존 CQL 타입 이름과 예약 타입 이름은 사용 불가.
• CREATE TRIGGER / DROP TRIGGER — 트리거 생성·제거. 트리거 로직은 Java(JVM) 언어로 작성되어 데이터베이스 외부에 존재하며, lib/triggers 하위 디렉토리에 배치하고 클러스터 시작 시 로드돼요. 요청된 DML 문이 발생하기 전에 발동되어 트랜잭션 원자성을 보장해요.
• CREATE FUNCTION / DROP FUNCTION — 사용자 정의 함수(UDF) 생성·제거. OR REPLACE로 같은 시그니처의 기존 함수 대체. RETURNS NULL ON NULL INPUT은 인자 중 하나라도 null이면 항상 null 반환, CALLED ON NULL INPUT은 항상 실행. 함수는 키스페이스에 속함.
• CREATE AGGREGATE / DROP AGGREGATE — 사용자 정의 집계 생성·제거. STYPE(상태 값 타입, 필수), INITCOND(초기 상태, 기본 null), SFUNC(상태 수정 함수), FINALFUNC(결과 반환 직전 호출).

데이터 조작 (Data Manipulation)

• INSERT — 테이블의 주어진 행에 하나 이상의 컬럼 기록. SQL과 달리 기본적으로 행의 기존 존재를 확인하지 않아요(없으면 생성, 있으면 갱신). IF NOT EXISTS 조건으로 삽입 전에 행이 없을 때만 삽입 가능하지만 Paxos가 사용되어 성능 비용이 있음. 모든 갱신은 원자적·격리적으로 적용. INSERT는 카운터를 지원하지 않음. JSON 구문 지원.
• UPDATE — 테이블의 주어진 행에 하나 이상의 컬럼 기록. <where-clause>는 PRIMARY KEY를 구성하는 모든 컬럼을 포함해야 함. IF 조건 가능(Paxos 사용). c = c + 3 형태는 카운터 증가/감소(카운터는 특정 값 할당이 아닌 증가/감소만 지원). id = id + <collection-literal>과 id[value1] = value2는 컬렉션용. id.field = <term>은 비동결 UDT의 단일 필드 설정용.
• <options> (UPDATE/INSERT): TIMESTAMP(연산 타임스탬프 설정), TTL(삽입 값의 유효 시간 초 단위. 삽입된 값에 적용되며 컬럼 자체가 아님. 후속 갱신도 TTL 초기화).
• DELETE — 컬럼과 행 삭제. DELETE 키워드 직후 컬럼 이름을 제공하면 그 컬럼만 삭제. id[value]는 비동결 컬렉션용, id.field는 비동결 UDT 삭제용. IN 절로 여러 행, 부등식 연산자로 행 범위 삭제 가능. TIMESTAMP 옵션 지원. IF 절로 조건부 삭제 가능.
• BATCH — 여러 수정 문(삽입/갱신 및 삭제)을 단일 문으로 그룹화. (1) 네트워크 왕복 절약, (2) 주어진 파티션 키에 속한 모든 갱신은 격리되어 수행, (3) 기본적으로 모든 연산이 LOGGED로 수행되어 모든 변형이 결국 완료되거나 하나도 완료되지 않도록 보장.
  • BATCH는 UPDATE, INSERT, DELETE 문만 포함 가능. SQL 트랜잭션의 완전한 대응물이 아님. 타임스탬프를 지정하지 않으면 모든 연산이 같은 타임스탬프로 적용되어 적용 순서가 나열 순서와 다를 수 있음.
  • UNLOGGED: batch log를 건너뛰어(여러 파티션에 걸친 배치 원자성 성능 비용을 피하려면) batchlog를 생략. 실패 시 배치가 부분적으로만 적용될 수 있음.
  • COUNTER: 배치된 카운터 갱신용. 카운터 갱신은 멱등적이지 않음.
  • BATCH는 TIMESTAMP 옵션 지원(배치 내 모든 문에 적용). 사용 시 배치 내 문에서는 TIMESTAMP를 사용하면 안 됨.

쿼리 (Queries)

• SELECT — 테이블의 하나 이상의 행에 대한 하나 이상의 컬럼을 읽어 결과 집합을 반환. JSON 키워드 사용 시 각 행의 결과는 json이라는 단일 컬럼을 포함.
  • <select-clause>: 컬럼 목록 또는 와일드카드(*). 셀렉터는 컬럼 이름 또는 함수. WRITETIME/MAXWRITETIME/TTL 함수는 컬럼 삽입 타임스탬프/만료 시간 선택, CAST는 타입 변환. 비동결 컬렉션이나 UDT 같은 다중 셀 컬럼에는 사용 불가. 맵·집합의 개별 값은 [ <term> ]로 선택, 슬라이스는 [ <term> ... <term> ]. AS로 별칭 지정(WHERE/ORDER BY는 원래 이름 참조). COUNT/COUNT(1)로 행 수.
  • <where-clause>: PRIMARY KEY의 일부이거나 보조 색인이 정의된 컬럼의 관계로 구성. 파티션 키에 비동등 관계(IN은 동등으로 간주)는 지원되지 않으나 TOKEN 메서드로 가능. 클러스터링 컬럼 관계는 연속 행 집합을 선택하는 관계로 제한. IN 관계는 파티션 키의 마지막 컬럼과 전체 기본 키의 마지막 컬럼에서만 허용. 클러스터링 컬럼을 튜플 표기로 그룹화 가능. CONTAINS는 컬렉션 컬럼에만, CONTAINS KEY는 맵 컬럼에만.
  • <order-by>: 반환 결과 순서 선택. 가능한 정렬은 테이블 CLUSTERING ORDER에 따라 제한 — 기본은 클러스터링 컬럼 유도 순서와 그 역순.
  • <group-by>: 선택된 컬럼 집합에서 같은 값을 공유하는 모든 행을 단일 행으로 압축. 파티션 키 수준 또는 클러스터링 컬럼 수준에서만 그룹화 가능. 집계 함수는 그룹별로 별도 값을 생성.
  • LIMIT(반환 행 수 제한)와 PER PARTITION LIMIT(주어진 파티션의 반환 행 수 제한).
  • ALLOW FILTERING: 기본적으로 CQL은 서버 측 필터링을 수반하지 않는 쿼리만 허용 — 이는 쿼리 시간이 반환되는 데이터 양에 비례한다는 예측 가능한 성능 때문. ALLOW FILTERING은 필터링을 요구하는 쿼리를 명시적으로 허용하지만 성능은 예측 불가할 수 있음.

데이터베이스 역할 (Database Roles)

• CREATE ROLE / ALTER ROLE / DROP ROLE / GRANT ROLE / REVOKE ROLE / LIST ROLES — 역할 기반 인증·인가. 기본적으로 역할은 LOGIN 권한이나 SUPERUSER 상태를 보유하지 않음. 역할은 계층적 권한 구조를 위해 다른 역할에 부여될 수 있으며, 이 계층에서 권한과 SUPERUSER 상태는 상속되지만 LOGIN 권한은 상속되지 않아요. 자세한 내용은 보안(security) 페이지 참조.
• 레거시 사용자 구문: Cassandra 2.2에서 역할이 도입되기 전에는 인증·인가가 USER 개념을 기반으로 했어요. 호환성을 위해 CREATE USER/ALTER USER/DROP USER/LIST USERS 레거시 구문이 보존되며, USER 중심 문은 ROLE 기반 등가물의 동의어예요. CREATE USER는 LOGIN 옵션이 true인 CREATE ROLE과 동등.

데이터베이스 아이덴티티 (Database Identities)

• ADD IDENTITY / DROP IDENTITY — 역할에 아이덴티티(identity) 추가·제거. 역할을 추가할 권한이 있는 사용자만 아이덴티티를 추가할 수 있고, 역할을 삭제할 권한이 있는 사용자만 제거할 수 있어요. 존재하는 아이덴티티 추가 시 IF NOT EXISTS, 존재하지 않는 아이덴티티 제거 시 IF EXISTS 옵션.

데이터 제어 (Data Control)

리소스에 대한 권한(permissions)은 역할에 부여돼요. 리소스 계층: ALL KEYSPACES → KEYSPACE → TABLE, ALL FUNCTIONS → KEYSPACE → FUNCTION, ALL ROLES → ROLE, ALL MBEANS → MBEAN. 권한은 계층의 어느 수준에서든 부여되며 아래로 흘러가요. 권한 수정은 기존 클라이언트 세션에 즉시 표시돼요.

전체 권한 집합: CREATE, ALTER, DROP, SELECT, MODIFY, AUTHORIZE, DESCRIBE, EXECUTE, UNMASK, SELECT_MASKED. 모든 권한이 모든 리소스 타입에 적용되지는 않아요(예: EXECUTE는 함수나 mbean에서만 관련). 권한별 리소스·연산 매트릭스:

permission	resource	operations
CREATE	ALL KEYSPACES	모든 키스페이스에서 CREATE KEYSPACE, CREATE TABLE
CREATE	KEYSPACE	지정된 키스페이스에서 CREATE TABLE
CREATE	ALL FUNCTIONS	모든 키스페이스에서 CREATE FUNCTION, CREATE AGGREGATE
CREATE	ALL ROLES	CREATE ROLE
ALTER	ALL KEYSPACES	모든 키스페이스에서 ALTER KEYSPACE, ALTER TABLE
ALTER	TABLE	ALTER TABLE
ALTER	ALL FUNCTIONS	기존 것을 대체하는 CREATE FUNCTION, CREATE AGGREGATE
ALTER	ALL ROLES	모든 역할에 대한 ALTER ROLE
DROP	ALL KEYSPACES	모든 키스페이스에서 DROP KEYSPACE, DROP TABLE
DROP	ALL FUNCTIONS	모든 키스페이스에서 DROP FUNCTION, DROP AGGREGATE
DROP	ALL ROLES	모든 역할에 대한 DROP ROLE
SELECT	ALL KEYSPACES	모든 테이블에 대한 SELECT
SELECT	ALL MBEANS	모든 mbean의 getter 메서드 호출
MODIFY	ALL KEYSPACES	모든 테이블에 대한 INSERT, UPDATE, DELETE, TRUNCATE
MODIFY	ALL MBEANS	모든 mbean의 setter 메서드 호출
AUTHORIZE	ALL KEYSPACES	모든 테이블에 대한 GRANT PERMISSION, REVOKE PERMISSION
AUTHORIZE	ALL FUNCTIONS	모든 함수에 대한 GRANT PERMISSION, REVOKE PERMISSION
AUTHORIZE	ALL ROLES	모든 역할에 대한 GRANT ROLE, REVOKE ROLE
DESCRIBE	ALL ROLES	모든 역할 또는 지정된 역할에 부여된 역할에 대한 LIST ROLES
DESCRIBE	ALL MBEANS	MBeanServer에서 모든 mbean에 대한 메타데이터 검색
EXECUTE	ALL FUNCTIONS	모든 함수를 사용한 SELECT, INSERT, UPDATE, CREATE AGGREGATE의 함수 사용
EXECUTE	ALL MBEANS	모든 mbean에 대한 작업 실행
UNMASK	ALL KEYSPACES	모든 테이블의 마스킹된 컬럼의 명확한 내용 보기
SELECT_MASKED	ALL KEYSPACES	모든 테이블에서 마스킹된 컬럼을 제한하는 SELECT

• GRANT PERMISSION / REVOKE PERMISSION / LIST PERMISSIONS — 권한 부여·해지·나열. GRANT ALL은 대상 리소스에 기반해 권한 집합을 자동 결정. CREATE KEYSPACE/CREATE TABLE/CREATE FUNCTION/CREATE AGGREGATE/CREATE ROLE로 리소스 생성 시 생성자는 새 리소스의 모든 적용 가능한 권한을 자동 부여받아요.

데이터 타입 (Data Types)

CQL은 네이티브 타입과 컬렉션 타입을 포함한 풍부한 데이터 타입 집합을 지원하며, AbstractType을 확장하는 Java 클래스를 통한 사용자 정의 타입도 가능해요. 네이티브 타입:

type	supported constants	description
ascii	strings	ASCII 문자 문자열
bigint	integers	64비트 부호 있는 long
blob	blobs	임의 바이트 (검증 없음)
boolean	booleans	true or false
counter	integers	카운터 컬럼 (64비트 부호 있는 값)
date	integers, strings	날짜 (해당 시간 값 없음)
decimal	integers, floats	가변 정밀도 십진수
double	integers	64비트 IEEE-754 부동소수점
float	integers, floats	32비트 IEEE-754 부동소수점
inet	strings	IP 주소 (IPv4 4바이트 또는 IPv6 16바이트)
int	integers	32비트 부호 있는 int
smallint	integers	16비트 부호 있는 int
text	strings	UTF8 인코딩 문자열
time	integers, strings	나노초 정밀도 시간
timestamp	integers, strings	타임스탬프
timeuuid	uuids	타입 1 UUID (충돌 없는 타임스탬프)
tinyint	integers	8비트 부호 있는 int
uuid	uuids	타입 1 또는 타입 4 UUID
varchar	strings	UTF8 인코딩 문자열
varint	integers	임의 정밀도 정수

• 타임스탬프 작업: timestamp 값은 epoch(1970-01-01 00:00:00 GMT) 이후 밀리초 수를 나타내는 64비트 부호 있는 정수로 인코딩되어 입력 가능하며, ISO 8601 형식 문자열로도 입력 가능(예: '2011-02-03 04:05+0000', +0000은 RFC 822 시간대, GMT는 +0000, 미국 태평양 표준시는 -0800). 시간대를 생략하면 코디네이터 노드 구성 시간대 기준. 시간대 지정이 권장됨.
• 날짜 작업: date 값은 epoch이 범위 중앙(2^31)인 일 수를 나타내는 32비트 부호 없는 정수. 형식 yyyy-mm-dd.
• 시간 작업: time 값은 자정 이후 나노초 수를 나타내는 64비트 부호 있는 정수. 형식 hh:mm:ss[.fffffffff].
• 카운터: counter 컬럼은 64비트 부호 있는 정수 값이며 증가·감소 연산만 지원. 값은 설정할 수 없음. PRIMARY KEY의 일부인 컬럼에 사용 불가, 카운터를 포함하는 테이블은 카운터만 포함해야 함.
• 컬렉션 작업: map(정렬된 키-값 쌍), set(고유 값의 정렬된 컬렉션), list(위치로 정렬된 비고유 값 컬렉션). 컬렉션은 항상 전체가 읽히고(내부 페이징 없음), 65535개 이상의 요소를 가질 수 없음(읽기는 65535 처음 요소만). 집합·맵의 삽입은 내부적으로 읽기-전-쓰기가 없지만 리스트의 일부 연산은 있음 — 가능하면 리스트보다 집합 선호. 리스트의 추가·앞에 추가는 멱등적이지 않아 타임아웃 시 재시도가 안전하지 않음. 리스트의 위치 설정·위치 제거·특정 값 발생 제거는 내부 읽기-전-쓰기를 수반해 더 느림.
• 벡터 작업: 벡터는 특정 데이터 타입의 비-null 값의 고정 크기 시퀀스. 리스트와 같은 리터럴 사용. 벡터의 개별 값 변경·선택 불가.

함수 (Functions)

CQL3는 내장 함수(네이티브 함수)와 사용자 정의 함수를 구분해요.

• Cast: cast 함수는 한 네이티브 타입을 다른 타입으로 변환. 변환은 Java의 의미론에 엄격히 의존. 지원 변환(예): ascii→text,varchar; bigint/counter/decimal/double/float/int/smallint/varint→다양한 숫자·문자 타입; boolean→text,varchar; date→timestamp; timestamp→date,text,varchar; timeuuid→timestamp,date,text,varchar; inet/time/uuid→text,varchar.
• Token: token 함수는 주어진 파티션 키에 대한 토큰을 계산. 반환 타입은 파티셔너에 따라 다름 — Murmur3Partitioner는 bigint, RandomPartitioner는 varint, ByteOrderedPartitioner는 blob.
• Uuid: uuid 함수는 매개변수 없이 INSERT/SET에 적합한 무작위 타입 4 uuid를 생성.
• Timeuuid 함수: now는 코디네이터에서 새로운 고유 timeuuid 생성(삽입에 유용, WHERE에는 부적합). min_timeuuid/max_timeuuid는 주어진 타임스탬프에 대한 가짜 최소/최대 timeuuid 반환 — RFC 4122를 따르지 않고 고유하지 않으므로 쿼리 전용으로만 사용.
• 시간 변환 함수: to_date, to_timestamp, to_unix_timestamp (입력 타입 timeuuid/timestamp/date).
• Blob 변환 함수: 각 네이티브 타입에 대해 type_as_blob와 blob_as_type — 예: bigint_as_blob(3)은 0x0000000000000003, blob_as_bigint(0x0000000000000003)은 3.

집계 (Aggregates)

집계 함수는 행 집합에 대해 동작하며 각 행의 값을 받아 전체 집합에 대한 하나의 값을 반환. 기본 집계: count(행 수 또는 주어진 컬럼의 비-null 값 수), max/min(최대/최소), sum(합), avg(평균).

사용자 정의 함수 (User-Defined Functions)

사용자 정의 함수(UDF)는 Cassandra에서 사용자 제공 코드의 실행을 허용해요. 기본적으로 Cassandra는 _Java_와 _JavaScript_로 함수 정의를 지원해요(Python, Ruby, Scala 같은 다른 JSR 223 스크립트 언어 지원은 3.0.11에서 제거). UDF는 Cassandra 스키마의 일부이므로 클러스터의 모든 노드에 자동 전파돼요. UDF는 오버로드될 수 있어요(같은 이름, 다른 인자 타입). 함수 실행 중 예외는 전체 문 실패를 초래. 컬렉션·튜플·UDT 같은 복합 타입을 인자와 반환 타입으로 사용 가능. 내재적으로 사용 가능한 udfContext 필드는 새 UDT(사용자 정의 타입)와 튜플 값을 만드는 기능을 제공해요. 자세한 내용은 함수(functions) 페이지 참조.

사용자 정의 집계 (User-Defined Aggregates)

사용자 정의 집계(UDA)는 UDF를 사용해 사용자 지정 집계 함수 생성. 각 집계는 STYPE 타입의 초기 상태(INITCOND, 기본 null)를 요구. 상태 함수의 첫 인자는 STYPE 타입이어야 하고 나머지 인자는 집계 인자 타입과 일치해야 해요. 상태 함수는 각 행마다 호출되고 그 반환이 새 상태가 돼요. 모든 행 처리 후 선택적 FINALFUNC이 마지막 상태 값으로 실행돼요. 자세한 내용은 함수(functions) 페이지 참조.

JSON 지원 (JSON Support)

Cassandra 2.2는 SELECT와 INSERT 문에 JSON 지원을 도입해요.

• SELECT JSON: 각 행을 단일 JSON 인코딩 맵으로 반환. 결과 맵 키는 정상 결과 집합의 컬럼 이름과 동일. 대문자 컬럼 이름은 INSERT JSON 동작과의 대칭을 위해 큰따옴표로 감싸짐.
• INSERT JSON: 단일 행으로 JSON 인코딩 맵 삽입. JSON 맵에서 생략된 컬럼은 NULL로 기본 설정(툼스톤 생성).
• JSON 인코딩: 가능하면 네이티브 JSON 표현으로 데이터 타입 표현·수용. 복합 타입(컬렉션, 튜플, UDT)은 네이티브 JSON 컬렉션(맵·리스트) 또는 JSON 인코딩 문자열로 표현.
• from_json() 함수: INSERT JSON과 유사하지만 단일 컬럼 값용. INSERT의 VALUES 절 또는 UPDATE/DELETE/SELECT의 컬럼 값으로 사용 가능(셀렉션 절에서는 불가).
• to_json() 함수: SELECT JSON과 유사하지만 단일 컬럼 값용. SELECT의 셀렉션 절에서만 사용 가능.

부록 A: CQL 키워드 (Appendix A: CQL Keywords)

CQL은 예약(reserved) 과 비예약(non-reserved) 키워드를 구분해요. 예약 키워드는 식별자로 사용할 수 없고 언어에 정말로 예약돼 있어요(큰따옴표로 감싸면 식별자로 사용 가능). 비예약 키워드는 특정 맥락에서만 특정 의미를 가지며 그 외에는 식별자로 사용될 수 있어요.

주요 예약 키워드(yes): ADD, ALLOW, ALTER, AND, APPLY, ASC, AUTHORIZE, BATCH, BEGIN, BY, COLUMNFAMILY, CREATE, DEFAULT, DELETE, DESC, DESCRIBE, DROP, ENTRIES, EXECUTE, FROM, FULL, GRANT, IF, IN, INDEX, INFINITY, INSERT, INTO, IS, KEYSPACE, LIMIT, MATERIALIZED, MBEAN, MBEANS, MODIFY, NAN, NORECURSIVE, NOT, NULL, OF, ON, OR, ORDER, PRIMARY, RENAME, REPLACE, REVOKE, SCHEMA, SELECT, SET, TABLE, TO, TOKEN, TRUNCATE, UNLOGGED, UNSET, UPDATE, USE, USING, VIEW, WHERE, WITH.

주요 비예약 키워드(no): AGGREGATE, ALL, AS, ASCII, BIGINT, BLOB, BOOLEAN, CALLED, CAST, CLUSTERING, COMPACT, CONTAINS, COUNT, COUNTER, CUSTOM, DATE, DECIMAL, DISTINCT, DOUBLE, DURATION, EXISTS, FILTERING, FINALFUNC, FLOAT, FROZEN, FUNCTION, FUNCTIONS, GROUP, INET, INITCOND, INPUT, INT, JSON, KEY, KEYS, KEYSPACES, LANGUAGE, LIKE, LIST, LOGIN, MAP, MASKED, NOLOGIN, NOSUPERUSER, OPTIONS, PARTITION, PASSWORD, PER, PERMISSION, PERMISSIONS, RETURNS, ROLE, ROLES, SELECT_MASKED, SFUNC, SMALLINT, STATIC, STORAGE, STYPE, SUPERUSER, TEXT, TIME, TIMESTAMP, TIMEUUID, TINYINT, TRIGGER, TTL, TUPLE, TYPE, UNMASK, USER, USERS, UUID, VALUES, VARCHAR, VARINT, WRITETIME.

부록 B: CQL 예약 타입 (Appendix B: CQL Reserved Types)

다음 타입 이름은 현재 CQL에서 사용되지 않지만 잠재적 미래 사용을 위해 예약돼 있어요. 사용자 정의 타입은 예약 타입 이름을 사용할 수 없어요.

bitstring
byte
complex
date
enum
interval
macaddr

변경 사항 (Changes)

각 CQL 버전의 변경 사항:

• 3.4.3: GROUP BY 지원 (CASSANDRA-10707).
• 3.4.2: 컬렉션의 요소·슬라이스 선택 지원 (CASSANDRA-7396); default_time_to_live를 가진 테이블에서 TTL 0 지정 시 TTL 제거; ALTER TABLE ADD/DROP이 여러 컬럼 지원; 새 PER PARTITION LIMIT 옵션 ([CASSANDRA-7017]); UDF가 새 UDFContext 인터페이스로 UDTValue·TupleValue 인스턴스 생성 가능 ([CASSANDRA-10818]); UDT가 비동결 형태로 저장 가능 ([CASSANDRA-7423]).
• 3.4.1: CAST 함수 추가.
• 3.4.0: 구체화 뷰(materialized views) 지원; DELETE가 부등식·IN 제한 지원; UPDATE가 IN 제한 지원.
• 3.3.1: TRUNCATE TABLE X 구문이 TRUNCATE X 별칭으로 허용.
• 3.3.0: 새 집계 추가; UDF(CREATE FUNCTION/DROP FUNCTION), UDA(CREATE AGGREGATE/DROP AGGREGATE) 지원; 이중 달러 문자열 리터럴; 역할(roles) 도입으로 사용자 기반 인증·접근 제어 대체; Date, Time 데이터 타입 추가; JSON 지원; Tinyint, Smallint 데이터 타입 추가; 새 시간 변환 함수 추가, dateOf/unixTimestampOf 폐기.
• 3.2.0: UDT 지원(CREATE TYPE/ALTER TYPE/DROP TYPE); CREATE INDEX가 컬렉션 컬럼 색인 지원(keys() 함수로 맵 키 색인); CONTAINS/CONTAINS KEY 연산자; 튜플 타입 추가; DROP INDEX가 키스페이스 선택 지정 지원.
• 3.1.7: SELECT가 클러스터링 컬럼 조합의 IN 절로 단일 파티션 내 여러 행 선택 지원; CREATE USER/DROP USER에 IF NOT EXISTS/IF EXISTS 구문.
• 3.1.6: 새 uuid 메서드; DELETE ... IF EXISTS 구문.
• 3.1.5: 관계에서 클러스터링 컬럼 그룹화; STATIC 컬럼 지원.
• 3.1.4: CREATE INDEX가 CUSTOM 색인 생성 시 옵션 지정 허용.
• 3.1.3: 타임스탬프 파서에 밀리초 정밀도 형식 추가.
• 3.1.2: NaN과 Infinity가 유효 부동소수점 상수로 추가(이제 예약 키워드).
• 3.1.1: SELECT가 DISTINCT로 파티션 키 나열 허용 ([CASSANDRA-4536]); c IN ? 구문; 명명 바인드 변수(:name).
• 3.1.0: ALTER TABLE DROP 재활성화(드롭된 컬럼 공간이 컴팩션 후 회수됨); SELECT의 별칭 지원; KEyspace/Table/Index에 IF NOT EXISTS/IF EXISTS; INSERT IF NOT EXISTS, UPDATE IF.
• 3.0.5: SELECT, UPDATE, DELETE가 빈 IN 관계 허용 ([CASSANDRA-5626]).
• 3.0.4: 사용자 지정 보조 색인 구문 갱신; 파티션 키의 비동등 조건은 정렬 파티셔너에서도 지원되지 않음(token 메서드 사용).
• 3.0.3: 사용자 지정 보조 색인 지원 추가.
• 3.0.2: 상수 타입 검증 수정(더 엄격); blob 상수 도입(문자열로 blob 입력은 폐기); 네이티브 타입을 blob으로 변환하는 함수 추가; token 함수가 select 절에서 허용.
• 3.0.1: 날짜 문자열을 유효한 timeuuid 값으로 더 이상 허용하지 않음; now, minTimeuuid, maxTimeuuid, dateOf, unixTimestampOf 메서드 추가; 부동소수점 상수 지수 표기(4.2E10) 지원.

버전 관리 (Versioning)

CQL 언어의 버전 관리는 Semantic Versioning 지침을 따르며, 버전은 X.Y.Z 형태를 가져요(X는 major, Y는 minor, Z는 patch). Cassandra 릴리스 버전과 CQL 언어 버전 사이에는 상관관계가 없어요.

version	description
Major	하위 호환되지 않는 변경이 도입될 때 major 버전을 올려야 함. 드물게 발생해야 함.
Minor	새롭지만 하위 호환되는 기능이 도입될 때 minor 버전 증가.
Patch	버그가 수정될 때 patch 버전 증가.

더 알아보기 (Learn more)

• Data definition
• Data manipulation
• Data types
• Functions
• Database Roles (security)