[TypeDB] TypeQL 개요

0. TypeQL 개요

- 공식홈페이지 소개 : " TypeQL is the declarative, strongly-typed, and intuitive query language used by TypeDB."

( TypeQL은 TypeDB에서 사용하는 선언적이고 강력한 타입의 직관적인 쿼리 언어입니다.)

- TypeDB를 조작하기 위한 자체 쿼리언어이다

1. TypeQL 주요 키워드 및 구문 ( $, sub, owns, isa, has)

본 포스팅은 문법을 설명하기 위함은 아니지만, 알아두면 아래의 내용들을 이해하는데 도움이 될것같아 먼저 서술함

1) $ : 변수 선언 기호

변수는 쿼리 내에서 재사용 가능

# $u, $n, $f 등은 모두 변수
match
  $u isa user, has username $n;
  $f (friend: $u) isa friendship;
  
  # 변수 사용 예시
  
  match
  # $person 변수에 user 엔티티를 할당
  $person isa user;
  
  # $person이 가진 username 속성 값을 $user_name 변수에 할당
  $person has username $user_name;
  
  # $person이 가진 email 속성 값을 $mail 변수에 할당
  $person has email $mail;
fetch
  $user_name;  # username 값만 가져오기
  $mail;       # email 값도 가져오기

2) sub : 상속/하위 타입 정의(계층 구조 정의)

"~의 하위 타입이다" 라는 뜻

define

  user sub entity;   	# user는 entity의 하위 타입이다 (user는 엔티티의 한 종류)
   
  admin sub user;		 # admin은 user의 하위 타입이다 (admin은 user의 한 종류)
  
  username sub attribute, value string;  	# username은 attribute의 하위 타입이다
  
  friendship sub relation;   # friendship은 relation의 하위 타입이다
  
  #계층구조 예시
  
  define
  # 사람은 엔티티의 하위 타입이고 이름(name)을 속성으로 가진다
  person sub entity,
    owns name;
  
  # 직원은 사람의 하위 타입이고 사번(employee-id) 속성으로 가진다
  employee sub person,
    owns employee-id;
  
  # 관리자는 직원의 하위 타입이고 부서(department)를 속성으로 가진다
  manager sub employee,
    owns department;

3) owns : 속성 소유 정의

엔티티나 관계가 특정 속성을 가질 수 있음을 정의

define
  # user는 username과 email 속성을 소유할 수 있음
  user sub entity,
    owns username,  # username 속성 소유 가능
    owns email;     # email 속성 소유 가능
  
  # friendship 관계도 속성을 소유할 수 있음
  friendship sub relation,
    relates friend,
    owns since,     # since 속성 소유 가능
    owns strength;  # strength 속성 소유 가능 (예: 친밀도)
   
# owns 수식어로는 @key, @unique, @card 등이 있다
define
  user sub entity,
    # @key: 이 속성은 고유해야 함 (중복 불가, 필수)
    owns email @key,
    
    # @unique: 이 속성은 고유해야 함 (중복 불가, 선택사항)
    owns username @unique,
    
    # @card: cardinality, 속성 개수 제한
    owns phone-number @card(1..3);  # 최소 1개, 최대 3개

4) isa : 인스턴스 타입 지정

" ~~ 는 ~~의 인스턴스이다" 라는 뜻
~~ISA계좌 아님~~
데이터 삽입이나 조회시 사용

# 데이터 삽입
insert
  # $u1은 user 타입의 인스턴스
  $u1 isa user, has username "김철수";
  
  # $f는 friendship 타입의 인스턴스
  $f isa friendship;
  
# 데이터 조회
match
  # user 타입의 모든 인스턴스를 $u에 할당
  $u isa user;
  
  # admin 타입의 모든 인스턴스를 $a에 할당
  $a isa admin;

5. has : 속성값 지정/조회

insert
  # user 인스턴스를 생성하면서 속성 값 지정
  $u isa user,
    has username "김철수",    # username 속성에 "김철수" 값 할당
    has email "kim@test.com"; # email 속성에 "kim@test.com" 값 할당
    
match
  # user 타입이면서 username 속성을 가진 것을 찾음
  # 그 username 값을 $n 변수에 할당
  $u isa user, has username $n;
  
  # 특정 username 값을 가진 user 찾기
  $u isa user, has username "김철수";
  
  # username이 "김철수"이고 email도 가진 user 찾기
  $u isa user,
    has username "김철수",
    has email $e;  # email 값은 $e 변수에 할당

2. 엔티티(Entity), 속성(Attribute), 관계(Relation)

1) 엔티티 (Entity)

독립적으로 존재할 수 있는 개념이나 객체
데이터베이스의 주요 대상(예: 사용자, 회사, 제품 등)
RDB의 테이블과 유사하지만 더 유연한 타입 계층 구조 지원

define  # 정의 시작
  
  user sub entity,			# user라는 엔티티 타입 정의 (entity의 하위 타입)
    owns username,  		# user는 username 속성을 가질 수 있음
    owns email;     		# user는 email 속성을 가질 수 있음
  
 
  company sub entity, 		# company라는 엔티티 타입 정의
    owns company-name;  	# company는 company-name 속성을 가질 수 있음

2) 속성 (Attribute)

엔티티나 관계가 가지는 실제 데이터 값
여러 엔티티가 동일한 속성 값을 공유 가능
속성 자체가 독립적인 개념으로 존재 (RDB의 컬럼 값과 차이점)

define

  username sub attribute, value string;   # username이라는 속성 타입 정의, 값의 타입은 문자열(string)
  
  email sub attribute, value string;   # email이라는 속성 타입 정의, 값의 타입은 문자열(string)
  
  company-name sub attribute, value string;   # company-name이라는 속성 타입 정의, 값의 타입은 문자열(string)

엔티티와 속성은 객체지향 프로그래밍의 "클래스-멤버변수"의 관계와 유사하지만 차이점이 있음

(1) TypeDB의 속성은 "엔티티와 관계없이 독립적으로 존재" (Java를 예시로 들면 Java는 각 객체마다 별도로 값을 저장하는 반면, TypeDB속성은 속성값을 한 곳에 저장하고 여로 엔티티가 참조)
(2) TypeDB에서는 속성 자체를 검색할 수 있음
(3) TypeDB에서는 속성도 속성을 가질 수 있음 (메타데이터)
그래프 데이터베이스의 노드-엣지 관계에 더 가까움

### 엔티티와 속성: OOP와의 비교

## 엔티티와 속성의 관계는 얼핏 보면 클래스와 멤버변수의 관계와 동일해보임

# Java 클래스
public class User {
    private String username;
    private String email;
}


# typeql
define
  user sub entity,
    owns username,
    owns email;


# 차이점
1. 속성의 독립성: TypeDB의 속성은 데이터베이스에 독립적으로 존재하며, 여러 엔티티가 동일한 속성 값을 공유할 수 있음
2. 속성의 속성: 속성 자체도 다른 속성을 가질 수 있음 (메타데이터)
3. 값 기반 검색: 속성 값으로 직접 검색하여 해당 값을 가진 모든 엔티티를 찾을 수 있음

3) 관계 (Relation)

엔티티들 간의 연결을 표현
관계 자체도 속성을 가질 수 있음
n-ary 관계 지원 (2개 이상의 엔티티 연결)
relates로 역할 정의, plays로 참여 가능한 엔티티 지정

define
  
  friendship sub relation,			# friendship이라는 관계 타입 정의 (relation의 하위 타입)
    relates friend,  				# friendship 관계는 'friend'라는 역할을 포함함
    owns since;      				# friendship 관계는 since 속성을 가질 수 있음
  

  user sub entity,					# user 엔티티가 friendship 관계에서 friend 역할을 할 수 있음
    plays friendship:friend;  		# 'friendship 관계의 friend 역할'을 수행
  

  since sub attribute, value datetime;		  # since라는 속성 타입 정의, 값의 타입은 날짜시간(datetime)

4) TypeDB의 최상위 타입(root type) : entity, relation, attribute

entity, relation, attribute 3가지 타입은 Java의 Object 클래스처럼 자동으로 존재함
사용자가 정의한 모든 타입은 이 3가지 중 하나의 하위 타입이어야 함

## 타입 계층 구조

entity (최상위 엔티티 타입)
  ├─ person
  │   ├─ employee
  │   │   ├─ manager
  │   │   └─ developer
  │   └─ customer
  ├─ company
  └─ product

relation (최상위 관계 타입)
  ├─ employment
  ├─ friendship
  └─ ownership

attribute (최상위 속성 타입)
  ├─ name (value string)
  ├─ age (value long)
  └─ email (value string)

5) 실제 사용 예시

스키마 정의

define
  # user 엔티티 타입 정의
  user sub entity,
    owns username,              # user는 username 속성 소유 가능
    plays friendship:friend;    # user는 friendship 관계에서 friend 역할 수행 가능
  
  # friendship 관계 타입 정의
  friendship sub relation,
    relates friend @card(2),    # friend 역할은 정확히 2명이어야 함 (cardinality)
    owns since;                 # friendship은 since 속성 소유 가능
  
  # 속성 타입들 정의
  username sub attribute, value string;    # 문자열 타입
  since sub attribute, value datetime;     # 날짜시간 타입

데이터 삽입 (Data pipeline)

insert
  # $u1 변수: "김철수"라는 username을 가진 user 엔티티 인스턴스 생성
  $u1 isa user, has username "김철수";
  
  # $u2 변수: "이영희"라는 username을 가진 user 엔티티 인스턴스 생성
  $u2 isa user, has username "이영희";
  
  # $f 변수: $u1과 $u2를 friend 역할로 연결하는 friendship 관계 생성
  # 이 관계는 2024-01-01이라는 since 속성 값을 가짐
  $f (friend: $u1, friend: $u2) isa friendship,
    has since 2024-01-01;

데이터 조회

match
  # $u 변수: user 타입의 인스턴스를 찾음
  # $n 변수: 그 user가 가진 username 속성 값을 찾음
  $u isa user, has username $n;
  
  # $f 변수: $u가 friend 역할로 참여하는 friendship 관계를 찾음
  $f (friend: $u) isa friendship;

# match에서 찾은 결과 중 $n(username 값)만 가져옴
fetch
  $n;

3. 스키마쿼리(Schema queries)와 데이터 파이프라인(Data piplines)

TypeQL은 크게 스키마쿼리( Schema queries) 와 데이터 파이프라인( Data pipelines) 으로 나뉜다.

+ TypeDB 3.0 이상부터 지원하는 함수(Functions)도 있다

스키마쿼리(Schema queries) : 스키마를 정의
- 단일 단계로 구성됨 (single-stage)
- 데이터베이스 스키마를 수정한다
- 성공확인 메세지 반환 / 별도의 내용 출력하지 않음
- 키워드 : define, undefine, redfine 등
데이터 파이프라인 (Data pipelines)
- 여러 단계로 구성됨 (mutli-stage)
- 데이터베이스에서 데이터를 읽고 쓰며 데이터를 출력함
- 키워드 : match, select, sort, reduce, insert, delete 등
함수(Functions) : 함수는 형식화된 입력 인수를 받는 데이터 파이프라인 템플릿
- 재사용이 가능한 쿼리 템플릿, 지정된 입력 인자를 받음
- 함수는 데이터를 쓰기/삭제 불가
- insert , delete 등의 쓰기 단계에(write stage) 포함할 수 없음
- 키워드 : match, select, sort, reduce 등
(참고) 스테이지(stage) : 데이터 파이프라인을 구성하는 개별 단계(step)
- 문장(statements) 으로 구성된다
- (예) define 스테이지는 다음과 같은 문장으로 구성됨 : user owns username
- (예) match 스테이지는 다음과 같은 문장으로 구성됨 : $u has username $n 또는 $type owns username

쿼리 유형(Query Type)	역할	스테이지 키워드 (Stage keywords)	Multi-stage 여부
스키마 쿼리 (Schema queries)	schema stages	define, undefine, redefine	no
데이터 파이프라인 (Data pipelines)	read and write stages	match, select, sort, reduce, insert, delete, …	yes
함수 (Functions)	read stages	match, select, sort, reduce, …	yes

4. 정의문과 패턴문(Definition vs Pattern statements)

Definition 과 patterns 는 TypeQL 에서 각자 다른 역할을 맡는다.

(1) Definition statements (변수 없음)

Schema queries는 항상 정의문과 함께 사용
타입 정의, 인터페이스 정의, 상속 관계 선언
type definition, interface definition, subtyping definition 3가지 종류로 나뉜다
- type definition : 적절한 키워드로 새로운 타입을 정의한다
- interface definition :

define
  entity user, plays friendship:friend;
  relation friendship, relates friend @card(2);

(2) Pattern statements (변수 있음)

Data pipelines와 Functions에서 사용
Data pipelines은 항상 패턴문과 함께 사용
변수를 포함한 쿼리 패턴
타입 조회, 데이터 검색, 함수 호출, 값 계산 등

match
  $some-type plays $some-role;
  friendship relates $some-role;

'DB\SQL > TypeDB' 카테고리의 다른 글

[TypeDB] TypeDB Core(CommunityEdition) 설치 (linux, podman) (0)	2026.01.18
[TypeDB] TypeDB 란? (1)	2026.01.15