Graph metadata#

Introduction#

The meta extension is a collection of helper functions for AgensGraph that simplify working with graph metadata. Its functions explore graph structures, validate labels, estimate sizes, analyze relationships, and handle Cypher types.

They let you inspect, monitor, and manage graphs in AgensGraph with less repetition and less effort.

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 it is installed, you can add the extension to any database with:

CREATE EXTENSION meta;

That makes all meta functions available in the database.

Functions#

The meta extension includes the following functions:

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 current graph_path.

Returns

  • label_name (name): Names of all labels in the specified graph, excluding system labels ag_vertex and ag_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 current graph_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 current graph_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 current graph_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 current graph_path.

Returns

  • kind (char): single character representing the label kind (v or e).

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 current graph_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 current graph_path.

  • pretty (boolean, optional): if true (default), returns a human-readable size (e.g., 42 MB). if false, 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 current graph_path.

  • pretty (boolean, optional): if true (default), returns a human-readable size (e.g., 42 MB). if false, 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 current graph_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 current graph_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: true if the graph exists, false otherwise.

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 to graph_path if not provided.

Returns

  • boolean: true if the label exists, false otherwise.

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 to graph_path if not provided.

Returns

  • boolean: true if the vertex label exists, false otherwise.

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 to graph_path if not provided.

Returns

  • boolean: true if the edge label exists, false otherwise.

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 to graph_path if 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 to graph_path if 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 include INTEGER, FLOAT, STRING, BOOLEAN, MAP, LIST, or NUMBER.

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, NULL or NUMBER).

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: true if the value matches the expected type, false otherwise.

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 to ag_edge.

  • graph (text, optional): The graph name. Defaults to the graph_path setting.

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 the graph_path setting.

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 the graph_path setting.

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;