Graph Meta
Introduction
The meta extension provides a collection of helper functions for AgensGraph that simplify working with graph metadata. It offers utilities for exploring graph structures, validating labels, estimating sizes, analyzing relationships, and handling Cypher types.
With these functions, users can more easily inspect, monitor, and manage graphs in AgensGraph, reducing repetitive tasks and improving overall efficiency.
Installation
The meta extension is included in the contrib directory of AgensGraph. To install it, first build and install AgensGraph with the contrib modules enabled.
Once installed, the extension can be added to any database with:
CREATE EXTENSION meta;
This will make all meta functions available for use within the database.
Functions
Follwing functions are included in meta extension:
meta.graphs
Description
Returns the list of all graphs available.
Arguments
None
Returns
Set of graph names
Example
SELECT * FROM meta.graphs();
graphname
-----------
social
company
test
meta.labels
Description
Returns all labels for a given graph. The system labels ag_vertex and ag_edge are not included in the result. If the graph argument is not provided, the function uses the current graph_path setting.
Arguments
graph(name, optional): Name of the graph. Defaults to the currentgraph_path.
Returns
label_name(name): Names of all labels in the specified graph, excluding system labelsag_vertexandag_edge.
Example
SELECT * FROM meta.labels('social');
label_name
------------
Person
Product
Transaction
meta.vertex_labels
Description
Returns all vertex labels defined in a given graph. The system label ag_vertex is excluded. If the graph argument is not provided, the function uses the current graph_path setting to determine the graph.
Arguments
graph(name, optional): Name of the graph. Defaults to the currentgraph_path.
Returns
label_name(name): Names of all vertex labels in the specified graph.
Example
SELECT * FROM meta.vertex_labels('social');
label_name
------------
Person
Product
Comment
meta.edge_labels
Description Returns all edge labels defined in a given graph. The system label ag_edge is excluded. If the graph argument is not provided, the function uses the current graph_path setting to determine the graph.
Arguments
graph(name, optional): Name of the graph. Defaults to the currentgraph_path.
Returns
label_name(name): Names of all edge labels in the specified graph.
Example
SELECT * FROM meta.edge_labels('social');
label_name
------------
Follows
Likes
Purchases
meta.label_id
Description
Returns the internal id of a specific label in a given graph. If the graph argument is not provided, the function uses the current graph_path setting. Raises an exception if the label does not exist in the graph.
Arguments
label(name, required): the name of the label whose id is to be retrieved.graph(name, optional): name of the graph. defaults to the currentgraph_path.
Returns
labid(int): internal id of the specified label.
Example
SELECT meta.label_id('Person', 'social');
labid
-------
5
meta.label_kind
Description
Returns the kind of a label (v for vertex, e for edge) in a given graph. If the graph argument is not provided, the function uses the current graph_path setting. Returns NULL if the label does not exist.
Arguments
label(name, required): the name of the label whose kind is to be retrieved.graph(name, optional): name of the graph. defaults to the currentgraph_path.
Returns
kind(char): single character representing the label kind (vore).
Example
SELECT meta.label_kind('Person', 'social');
kind
------
v
meta.label_name
Description
Returns the name of a label given its ID (labid) or OID in a specific graph. If the graph argument is not provided, the function uses the current graph_path setting. Raises a notice if the label does not exist.
Arguments
labelid(int, required): the ID or OID of the label.graph(name, optional): name of the graph. defaults to the currentgraph_path.
Returns
label_name(text): the name of the label.
Example
SELECT meta.label_name(5, 'social');
label_name
------------
Person
meta.graph_size
Description
Returns the total size of a graph, including all its labels. If the graph_name argument is not provided, the function uses the current graph_path setting. The size can be returned in a human-readable format or as raw bytes.
Arguments
graph_name(name, optional): the name of the graph. defaults to the currentgraph_path.pretty(boolean, optional): iftrue(default), returns a human-readable size (e.g.,42 MB). iffalse, returns the size in bytes as text.
Returns
size(text): total size of the graph.
Examples
SELECT meta.graph_size('social');
graph_size
------------
123 MB
SELECT meta.graph_size('social', false);
graph_size
------------
129394816
meta.label_size
Description
Returns the total size of a specific label, including its indexes. If the graph argument is not provided, the function uses the current graph_path setting. The size can be returned in a human-readable format or as raw bytes.
Arguments
labelname(text): the name of the label.graph(name, optional): the graph that contains the label. defaults to the currentgraph_path.pretty(boolean, optional): iftrue(default), returns a human-readable size (e.g.,42 MB). iffalse, returns the size in bytes as text.
Returns
size(text): total size of the label including indexes.
Examples
SELECT meta.label_size('person');
label_size
------------
42 MB
SELECT meta.label_size('person', pretty => false);
label_size
------------
44040192
meta.count
Description
Returns the exact number of nodes or edges for the specified label. If the graph argument is not provided, the function uses the current graph_path setting.
Arguments
labelname(text): the label whose elements are being counted.graph(name, optional): the graph that contains the label. defaults to the currentgraph_path.
Returns
count(bigint): the exact number of elements (nodes or edges) in the label.
Example
-- 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');
meta.estimated_count
Description
Returns an estimated number of elements (nodes or edges) for a given label based on PostgreSQL statistics (pg_class.reltuples). If the graph argument is not provided, the function uses the current graph_path setting. This is faster than meta.count but may be inaccurate.
Note: If statistics are not available, the function may return NULL. Run
ANALYZE "graph"."label"to gather statistics.
Arguments
labelname(text): the label whose estimated element count is returned.graph(name, optional): the graph containing the label. defaults to the currentgraph_path.
Returns
estimated_count(bigint): estimated number of elements in the label.
Example
-- 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');
meta.graph_exists
Description
Checks whether a graph with the specified name exists.
Arguments
graph(name): Name of the graph to check.
Returns
boolean:trueif the graph exists,falseotherwise.
Example
SELECT meta.graph_exists('social');
?column?
----------
t
meta.label_exists
Description
Checks whether a label exists in the specified graph. If the graph is not provided, it uses the current graph_path setting.
Arguments
labelname(text): Name of the label to check.graph(name, optional): Name of the graph. Defaults tograph_pathif not provided.
Returns
boolean:trueif the label exists,falseotherwise.
Example
SELECT meta.label_exists('Person', 'social');
?column?
----------
t
meta.vertex_label_exists
Description
Checks whether a vertex label exists in the specified graph. If the graph is not provided, it uses the current graph_path setting.
Arguments
labelname(text): Name of the vertex label to check.graph(name, optional): Name of the graph. Defaults tograph_pathif not provided.
Returns
boolean:trueif the vertex label exists,falseotherwise.
Example
SELECT meta.vertex_label_exists('Person', 'social');
?column?
----------
t
meta.edge_label_exists
Description
Checks whether an edge label exists in the specified graph. If the graph is not provided, it uses the current graph_path setting.
Arguments
labelname(text): Name of the edge label to check.graph(name, optional): Name of the graph. Defaults tograph_pathif not provided.
Returns
boolean:trueif the edge label exists,falseotherwise.
Example
SELECT meta.edge_label_exists('Follows', 'social');
?column?
----------
t
meta.get_child_labels
Description
Returns all child labels that inherit from the specified parent label. If the graph is not provided, it uses the current graph_path setting.
Arguments
parent_label(text): Name of the parent label.graph(name, optional): Name of the graph. Defaults tograph_pathif not provided.
Returns
table(labelname name): A set of child label names.
Example
SELECT * FROM meta.get_child_labels('Person', 'social');
labelname
-----------
Employee
Customer
meta.get_parent_labels
Description
Returns all parent labels from which the specified child label inherits. If the graph is not provided, it uses the current graph_path setting.
Arguments
child_label(text): Name of the child label.graph(name, optional): Name of the graph. Defaults tograph_pathif not provided.
Returns
table(labelname name): A set of parent label names.
Example
SELECT * FROM meta.get_parent_labels('Employee', 'social');
labelname
-----------
Person
meta.cypher_type
Description
Determines the corresponding Cypher type of a given value. Supports standard types, JSON/JSONB, and numeric distinctions.
Arguments
element(anyelement): The value whose Cypher type should be determined.
Returns
text: The Cypher type as a string. Possible values includeINTEGER,FLOAT,STRING,BOOLEAN,MAP,LIST, orNUMBER.
Example
SELECT meta.cypher_type(42) AS result;
result
-------
INTEGER
SELECT meta.cypher_type('{"key": "value"}'::jsonb) AS result;
result
-------
MAP
meta.cypher_types
Description
Returns a JSONB object mapping each key of the input JSONB object to its corresponding Cypher type. Raises an error if the input is not a JSON object.
Arguments
properties(jsonb): A JSONB object whose keys will be mapped to Cypher types.
Returns
jsonb: A JSONB object where each key corresponds to the input keys and the values are the detected Cypher types (INTEGER,FLOAT,STRING,BOOLEAN,MAP,LIST,NULLorNUMBER).
Example
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"}
meta.is_cypher_type
Description
Checks if a given value matches the specified Cypher type. Supports types: NULL, INTEGER, FLOAT, STRING, BOOLEAN, MAP, LIST, and NUMBER.
Arguments
value(anyelement): The value to check.expected_type(text): The expected Cypher type.
Returns
boolean:trueif the value matches the expected type,falseotherwise.
Example
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
meta.count_self_loops
Description
Returns the number of self-loops (edges where the start and end vertices are the same) in a specified graph.
If no relationship is provided, all edges are considered regardless of edge label. If no graph is provided, the graph_path setting is used.
Arguments
relationship(text, optional): The name of the relationship/edge label to check. Defaults toag_edge.graph(text, optional): The graph name. Defaults to thegraph_pathsetting.
Returns
bigint: Number of self-loop edges.
Example
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)
meta.edge_density
Description
Calculates the edge density of a graph, defined as the ratio of existing edges to the maximum possible number of edges.
If no graph is provided, the graph_path setting is used.
Arguments
graph(name, optional): The graph name. Defaults to thegraph_pathsetting.
Returns
float: Edge density of the graph.
Example
-- 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;
meta.estimated_edge_density
Description
Provides an estimated edge density of a graph using PostgreSQL statistics (pg_class.reltuples) instead of exact counts.
This is faster for large graphs but maybe inaccurate. Uses graph_path if no graph name is provided.
Arguments
graph(name, optional): The graph name. Defaults to thegraph_pathsetting.
Returns
float: Estimated edge density of the graph.
Example
-- 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;