<!-- check-examples: skip because every example needs the `meta` extension. -->

{#graph-metadata-graph-metadata}
# 그래프 메타데이터

{#graph-metadata-introduction}
## 소개

meta 확장은 그래프 메타데이터를 다루는 일을 간단하게 해 주는 AgensGraph용 보조 함수 모음입니다.
이 함수들은 그래프 구조를 살피고, 레이블을 확인하고, 크기를 추정하고, 관계를 분석하고, Cypher 타입을 다룹니다.

AgensGraph의 그래프를 더 적은 되풀이와 더 적은 수고로 들여다보고, 감시하고, 관리할 수 있게 해 줍니다.

{#graph-metadata-installation}
## 설치
meta 확장은 AgensGraph의 contrib 디렉터리에 들어 있습니다.
설치하려면 먼저 contrib 모듈을 켠 채로 AgensGraph를 빌드해 설치하십시오.

설치한 뒤에는 다음으로 어느 데이터베이스에나 확장을 추가할 수 있습니다:

```sql
CREATE EXTENSION meta;
```

그러면 그 데이터베이스에서 모든 meta 함수를 쓸 수 있습니다.

{#graph-metadata-functions}
## 함수

meta 확장에는 다음 함수들이 들어 있습니다:

{#graph-metadata-metagraphs}
### meta.graphs

**설명**  
쓸 수 있는 모든 그래프의 목록을 반환합니다.

**인수**  
- 없음

**반환**  
- 그래프 이름의 집합

**예제**  
```sql
SELECT * FROM meta.graphs();

 graphname
-----------
 social
 company
 test
```

{#graph-metadata-metalabels}
### meta.labels

**설명**  
주어진 그래프의 모든 레이블을 반환합니다. 시스템 레이블인 `ag_vertex`와 `ag_edge`는 결과에 들어가지 않습니다. `graph` 인수를 주지 않으면 현재 `graph_path` 설정을 씁니다.

**인수**  
- `graph` (name, 선택): 그래프의 이름입니다. 기본값은 현재 `graph_path`입니다.

**반환**  
- `label_name` (name): 지정한 그래프의 모든 레이블 이름이며, 시스템 레이블 `ag_vertex`와 `ag_edge`는 뺍니다.

**예제**  
```sql
SELECT * FROM meta.labels('social');

 label_name
------------
 Person
 Product
 Transaction
```

{#graph-metadata-metavertex_labels}
### meta.vertex_labels

**설명**  
주어진 그래프에 정의된 모든 정점 레이블을 반환합니다. 시스템 레이블 `ag_vertex`는 뺍니다. `graph` 인수를 주지 않으면 현재 `graph_path` 설정으로 그래프를 정합니다.

**인수**  
- `graph` (name, 선택): 그래프의 이름입니다. 기본값은 현재 `graph_path`입니다.

**반환**  
- `label_name` (name): 지정한 그래프의 모든 정점 레이블 이름입니다.

**예제**  
```sql
SELECT * FROM meta.vertex_labels('social');

 label_name
------------
 Person
 Product
 Comment
```

{#graph-metadata-metaedge_labels}
### meta.edge_labels

**설명**
주어진 그래프에 정의된 모든 간선 레이블을 반환합니다. 시스템 레이블 ag_edge는 뺍니다. graph 인수를 주지 않으면 현재 graph_path 설정으로 그래프를 정합니다.

**인수**

- `graph` (name, 선택): 그래프의 이름입니다. 기본값은 현재 `graph_path`입니다.

**반환**

- `label_name` (name): 지정한 그래프의 모든 간선 레이블 이름입니다.

**예제**
```sql
SELECT * FROM meta.edge_labels('social');

 label_name
------------
 Follows
 Likes
 Purchases
```

{#graph-metadata-metalabel_id}
### meta.label_id

**설명**  
주어진 그래프에서 특정 레이블의 내부 id를 반환합니다. `graph` 인수를 주지 않으면 현재 `graph_path` 설정을 씁니다. 그 레이블이 그래프에 없으면 예외를 냅니다.

**인수**  
- `label` (name, 필수): id를 얻으려는 레이블의 이름입니다.  
- `graph` (name, 선택): 그래프의 이름입니다. 기본값은 현재 `graph_path`입니다.

**반환**  
- `labid` (int): 지정한 레이블의 내부 id입니다.

**예제**  
```sql
SELECT meta.label_id('Person', 'social');

 labid
-------
     5
```

{#graph-metadata-metalabel_kind}
### meta.label_kind

**설명**  
주어진 그래프에서 레이블의 종류(정점이면 `v`, 간선이면 `e`)를 반환합니다. `graph` 인수를 주지 않으면 현재 `graph_path` 설정을 씁니다. 그 레이블이 없으면 `NULL`을 반환합니다.

**인수**  
- `label` (name, 필수): 종류를 얻으려는 레이블의 이름입니다.  
- `graph` (name, 선택): 그래프의 이름입니다. 기본값은 현재 `graph_path`입니다.

**반환**  
- `kind` (char): 레이블 종류를 나타내는 한 글자(`v` 또는 `e`)입니다.

**예제**  
```sql
SELECT meta.label_kind('Person', 'social');

 kind
------
 v
```

{#graph-metadata-metalabel_name}
### meta.label_name

**설명**  
특정 그래프에서 ID(`labid`)나 OID로 레이블의 이름을 반환합니다. `graph` 인수를 주지 않으면 현재 `graph_path` 설정을 씁니다. 그 레이블이 없으면 notice를 냅니다.

**인수**  
- `labelid` (int, 필수): 레이블의 ID 또는 OID입니다.  
- `graph` (name, 선택): 그래프의 이름입니다. 기본값은 현재 `graph_path`입니다.

**반환**  
- `label_name` (text): 레이블의 이름입니다.

**예제**  
```sql
SELECT meta.label_name(5, 'social');

 label_name
------------
 Person
```

{#graph-metadata-metagraph_size}
### meta.graph_size

**설명**  
그래프의 전체 크기를 모든 레이블을 포함해 반환합니다. `graph_name` 인수를 주지 않으면 현재 `graph_path` 설정을 씁니다. 크기는 사람이 읽기 좋은 형태로도, 바이트 수로도 반환할 수 있습니다.

**인수**  
- `graph_name` (name, 선택): 그래프의 이름입니다. 기본값은 현재 `graph_path`입니다.  
- `pretty` (boolean, 선택): `true`(기본값)이면 사람이 읽기 좋은 크기(예: `42 MB`)를 반환하고, `false`이면 바이트 수를 text로 반환합니다.

**반환**  
- `size` (text): 그래프의 전체 크기입니다.

**예제**
```sql
SELECT meta.graph_size('social');

 graph_size
------------
 123 MB

SELECT meta.graph_size('social', false);

 graph_size
------------
 129394816
```

{#graph-metadata-metalabel_size}
### meta.label_size

**설명**  
특정 레이블의 전체 크기를 인덱스를 포함해 반환합니다. `graph` 인수를 주지 않으면 현재 `graph_path` 설정을 씁니다. 크기는 사람이 읽기 좋은 형태로도, 바이트 수로도 반환할 수 있습니다.

**인수**  
- `labelname` (text): 레이블의 이름입니다.  
- `graph` (name, 선택): 그 레이블이 든 그래프입니다. 기본값은 현재 `graph_path`입니다.  
- `pretty` (boolean, 선택): `true`(기본값)이면 사람이 읽기 좋은 크기(예: `42 MB`)를 반환하고, `false`이면 바이트 수를 text로 반환합니다.

**반환**  
- `size` (text): 인덱스를 포함한 레이블의 전체 크기입니다.

**예제**
```sql
SELECT meta.label_size('person');

 label_size
------------
 42 MB

SELECT meta.label_size('person', pretty => false);

 label_size
------------
 44040192
```

{#graph-metadata-metacount}
### meta.count

**설명**  
지정한 레이블의 정점 또는 간선 개수를 정확히 반환합니다. `graph` 인수를 주지 않으면 현재 `graph_path` 설정을 씁니다.

**인수**  
- `labelname` (text): 요소 수를 셀 레이블입니다.  
- `graph` (name, 선택): 그 레이블이 든 그래프입니다. 기본값은 현재 `graph_path`입니다.

**반환**  
- `count` (bigint): 그 레이블의 요소(정점 또는 간선) 개수입니다.

**예제**  
```sql
-- Count all nodes in the 'person' label
SELECT meta.count('person');

-- Count all edges in the 'friendship' label of the 'social' graph
SELECT meta.count('friendship', 'social');
```

{#graph-metadata-metaestimated_count}
### meta.estimated_count

**설명**  
PostgreSQL 통계(`pg_class.reltuples`)를 바탕으로 주어진 레이블의 요소(정점 또는 간선) 개수를 추정해 반환합니다. `graph` 인수를 주지 않으면 현재 `graph_path` 설정을 씁니다. `meta.count`보다 빠르지만 정확하지 않을 수 있습니다.
> 참고: 통계가 없으면 NULL을 반환할 수 있습니다. `ANALYZE "graph"."label"` 로 통계를 수집하십시오.

**인수**  
- `labelname` (text): 추정 요소 수를 얻을 레이블입니다.  
- `graph` (name, 선택): 그 레이블이 든 그래프입니다. 기본값은 현재 `graph_path`입니다.

**반환**  
- `estimated_count` (bigint): 그 레이블의 추정 요소 개수입니다.

**예제**  
```sql
-- Get estimated count of nodes in the 'person' label
SELECT meta.estimated_count('person');

-- Get estimated count of edges in the 'friendship' label of the 'social' graph
SELECT meta.estimated_count('friendship', 'social');
```

{#graph-metadata-metagraph_exists}
### meta.graph_exists

**설명**  
지정한 이름의 그래프가 있는지 확인합니다.

**인수**  
- `graph` (name): 확인할 그래프의 이름입니다.

**반환**  
- `boolean`: 그래프가 있으면 `true`, 없으면 `false`입니다.

**예제**  
```sql
SELECT meta.graph_exists('social');

 ?column? 
----------
 t
```

{#graph-metadata-metalabel_exists}
### meta.label_exists

**설명**  
지정한 그래프에 레이블이 있는지 확인합니다. 그래프를 주지 않으면 현재 `graph_path` 설정을 씁니다.

**인수**  
- `labelname` (text): 확인할 레이블의 이름입니다.  
- `graph` (name, 선택): 그래프의 이름입니다. 주지 않으면 `graph_path`를 씁니다.

**반환**  
- `boolean`: 레이블이 있으면 `true`, 없으면 `false`입니다.

**예제**  
```sql
SELECT meta.label_exists('Person', 'social');

 ?column? 
----------
 t
```

{#graph-metadata-metavertex_label_exists}
### meta.vertex_label_exists

**설명**  
지정한 그래프에 정점 레이블이 있는지 확인합니다. 그래프를 주지 않으면 현재 `graph_path` 설정을 씁니다.

**인수**  
- `labelname` (text): 확인할 정점 레이블의 이름입니다.  
- `graph` (name, 선택): 그래프의 이름입니다. 주지 않으면 `graph_path`를 씁니다.

**반환**  
- `boolean`: 정점 레이블이 있으면 `true`, 없으면 `false`입니다.

**예제**  
```sql
SELECT meta.vertex_label_exists('Person', 'social');

 ?column? 
----------
 t
```

{#graph-metadata-metaedge_label_exists}
### meta.edge_label_exists

**설명**  
지정한 그래프에 간선 레이블이 있는지 확인합니다. 그래프를 주지 않으면 현재 `graph_path` 설정을 씁니다.

**인수**  
- `labelname` (text): 확인할 간선 레이블의 이름입니다.  
- `graph` (name, 선택): 그래프의 이름입니다. 주지 않으면 `graph_path`를 씁니다.

**반환**  
- `boolean`: 간선 레이블이 있으면 `true`, 없으면 `false`입니다.

**예제**  
```sql
SELECT meta.edge_label_exists('Follows', 'social');

 ?column? 
----------
 t
```

{#graph-metadata-metaget_child_labels}
### meta.get_child_labels

**설명**  
지정한 부모 레이블을 상속하는 모든 자식 레이블을 반환합니다. 그래프를 주지 않으면 현재 `graph_path` 설정을 씁니다.

**인수**  
- `parent_label` (text): 부모 레이블의 이름입니다.  
- `graph` (name, 선택): 그래프의 이름입니다. 주지 않으면 `graph_path`를 씁니다.

**반환**  
- `table(labelname name)`: 자식 레이블 이름의 집합입니다.

**예제**  
```sql
SELECT * FROM meta.get_child_labels('Person', 'social');

 labelname 
-----------
 Employee
 Customer
```

{#graph-metadata-metaget_parent_labels}
### meta.get_parent_labels

**설명**  
지정한 자식 레이블이 상속하는 모든 부모 레이블을 반환합니다. 그래프를 주지 않으면 현재 `graph_path` 설정을 씁니다.

**인수**  
- `child_label` (text): 자식 레이블의 이름입니다.  
- `graph` (name, 선택): 그래프의 이름입니다. 주지 않으면 `graph_path`를 씁니다.

**반환**  
- `table(labelname name)`: 부모 레이블 이름의 집합입니다.

**예제**  
```sql
SELECT * FROM meta.get_parent_labels('Employee', 'social');

 labelname 
-----------
 Person
```

{#graph-metadata-metacypher_type}
### meta.cypher_type

**설명**  
주어진 값에 대응하는 Cypher 타입을 판정합니다. 표준 타입과 JSON/JSONB, 그리고 수치 구분을 지원합니다.

**인수**  
- `element` (anyelement): Cypher 타입을 판정할 값입니다.

**반환**  
- `text`: 문자열로 된 Cypher 타입입니다. `INTEGER`·`FLOAT`·`STRING`·`BOOLEAN`·`MAP`·`LIST`·`NUMBER` 등이 나올 수 있습니다.

**예제**  
```psql
SELECT meta.cypher_type(42) AS result;
result
-------
INTEGER

SELECT meta.cypher_type('{"key": "value"}'::jsonb) AS result;
result
-------
MAP
```

{#graph-metadata-metacypher_types}
### meta.cypher_types

**설명**  
입력 JSONB 객체의 각 키를 그에 대응하는 Cypher 타입에 대응시킨 JSONB 객체를 반환합니다. 입력이 JSON 객체가 아니면 오류를 냅니다.

**인수**  
- `properties` (jsonb): 키를 Cypher 타입에 대응시킬 JSONB 객체입니다.

**반환**  
- `jsonb`: 각 키가 입력의 키에 대응하고 값이 판정된 Cypher 타입(`INTEGER`·`FLOAT`·`STRING`·`BOOLEAN`·`MAP`·`LIST`·`NULL`·`NUMBER`)인 JSONB 객체입니다.

**예제**  
```psql
SELECT meta.cypher_types('{"key": "value", "arr": [1, 2, 3], "num": 123, "float": 45.67, "bool": true, "null": null}'::jsonb);
                                              cypher_types                                               
---------------------------------------------------------------------------------------------------------
 {"arr": "LIST", "key": "STRING", "num": "INTEGER", "bool": "BOOLEAN", "null": "NULL", "float": "FLOAT"}
```

{#graph-metadata-metais_cypher_type}
### meta.is_cypher_type

**설명**  
주어진 값이 지정한 Cypher 타입과 맞는지 확인합니다. 지원하는 타입은 `NULL`·`INTEGER`·`FLOAT`·`STRING`·`BOOLEAN`·`MAP`·`LIST`·`NUMBER`입니다.

**인수**  
- `value` (anyelement): 확인할 값입니다.  
- `expected_type` (text): 기대하는 Cypher 타입입니다.

**반환**  
- `boolean`: 값이 기대한 타입과 맞으면 `true`, 아니면 `false`입니다.

**예제**  
```sql
SELECT meta.is_cypher_type(123, 'INTEGER') AS result;
result
-------
t

SELECT meta.is_cypher_type('Alice', 'STRING') AS result;
result
-------
t

SELECT meta.is_cypher_type('NULL'::jsonb, 'NULL') AS result;
result
-------
t
```

{#graph-metadata-metacount_self_loops}
### meta.count_self_loops

**설명**  
지정한 그래프의 셀프 루프(시작 정점과 끝 정점이 같은 간선) 개수를 반환합니다.  
관계를 주지 않으면 간선 레이블과 무관하게 모든 간선을 셉니다. 그래프를 주지 않으면 `graph_path` 설정을 씁니다.

**인수**  
- `relationship` (text, 선택): 확인할 관계/간선 레이블의 이름입니다. 기본값은 `ag_edge`입니다.  
- `graph` (text, 선택): 그래프 이름입니다. 기본값은 `graph_path` 설정입니다.

**반환**  
- `bigint`: 셀프 루프 간선의 개수입니다.

**예제**  
```psql
MATCH (a:person {name: 'Bob'})
CREATE (a)-[:"KNOWS"]->(a);
MATCH (a:animal {name: 'Spot'})
CREATE (a)-[:"HAS_PET"]->(a);
SELECT meta.count_self_loops(graph=>'social');
 count_self_loops 
------------------
                2
(1 row)

SELECT meta.count_self_loops('HAS_PET');
 count_self_loops 
------------------
                1
(1 row)
```

{#graph-metadata-metaedge_density}
### meta.edge_density

**설명**  
그래프의 간선 밀도를 계산합니다. 실제 간선 수를 가능한 최대 간선 수로 나눈 비율입니다.  
그래프를 주지 않으면 `graph_path` 설정을 씁니다.

**인수**  
- `graph` (name, 선택): 그래프 이름입니다. 기본값은 `graph_path` 설정입니다.

**반환**  
- `float`: 그래프의 간선 밀도입니다.

**예제**  
```sql
-- Calculate edge density for the current graph
SELECT meta.edge_density() AS result;

-- Calculate edge density for a specific graph
SELECT meta.edge_density('social_graph') AS result;
```

{#graph-metadata-metaestimated_edge_density}
### meta.estimated_edge_density

**설명**  
정확한 개수 대신 PostgreSQL 통계(`pg_class.reltuples`)를 써서 그래프의 간선 밀도를 추정합니다.  
큰 그래프에서는 더 빠르지만 정확하지 않을 수 있습니다. 그래프 이름을 주지 않으면 `graph_path`를 씁니다.

**인수**  
- `graph` (name, 선택): 그래프 이름입니다. 기본값은 `graph_path` 설정입니다.

**반환**  
- `float`: 그래프의 추정 간선 밀도입니다.

**예제**  
```sql
-- Estimate edge density for the current graph
SELECT meta.estimated_edge_density() AS result;

-- Estimate edge density for a specific graph
SELECT meta.estimated_edge_density('social_graph') AS result;
```