English

Installation and Management

Installation

1. Compilation

--enable-enterprise --with-age

2. Configuration

Add age to shared_preload_libraries in postgresql.conf:

shared_preload_libraries = 'xxx,age'

3. Loading the Extension

After restarting the server, install the extension:

CREATE EXTENSION age;

4. Per-Session Setup

Each time you connect to a YMatrix AGE database, perform the following steps:

Load the AGE library:

LOAD 'age';

Add ag_catalog to search_path to simplify function and type references:

SET search_path = ag_catalog, "$user", public;

Graph Management

A graph consists of a set of vertices and edges. Each vertex and edge carries a property map. A vertex is a fundamental graph object that can exist independently of all other elements in the graph. An edge establishes a directed connection between two vertices.

Creating a Graph

Use the create_graph function in the ag_catalog schema.

create_graph()

Syntax: create_graph(graph_name);

Returns:

void

Parameters:

Name	Description
`graph_name`	Name of the graph to create

Notes:

The function returns no data. Absence of an error indicates successful creation.
Required catalog tables are created automatically.

Example:

SELECT * FROM ag_catalog.create_graph('graph_name');
NOTICE:  graph "graph_name" has been created
 create_graph
--------------

(1 row)

Dropping a Graph

Use the drop_graph function in the ag_catalog schema.

drop_graph()

Syntax: drop_graph(graph_name, cascade);

Returns:

void

Parameters:

Name	Description
`graph_name`	Name of the graph to drop
`cascade`	Boolean (default `false`). Must be `true` to drop dependent labels and data; otherwise, an error is raised.

Notes:

The function returns no data. Absence of an error indicates successful deletion.
The cascade argument must be explicitly set to true. Passing false or omitting it results in an error.

Examples:

SELECT * FROM ag_catalog.drop_graph('graph_name', true);
NOTICE:  drop cascades to 2 other objects
DETAIL:  drop cascades to table graph_name._ag_label_vertex
drop cascades to table graph_name._ag_label_edge
NOTICE:  graph "graph_name" has been dropped
 drop_graph
------------

(1 row)

SELECT drop_graph('graph');
ERROR:  drop_graph second argument must be TRUE

SELECT drop_graph('graph', false);
ERROR:  drop_graph second argument must be TRUE

Graph Storage in PostgreSQL

When a graph is created with AGE, a dedicated namespace named graph_name is generated. The graph name and its associated namespace are recorded in the ag_catalog.ag_graph catalog table:

SELECT create_graph('new_graph');
NOTICE:  graph "new_graph" has been created
 create_graph 
--------------

(1 row)

SELECT * FROM ag_catalog.ag_graph;

   name    | namespace 
-----------+-----------
 new_graph | new_graph
(1 row)

After graph creation, two system tables are automatically created under the graph’s namespace: _ag_label_vertex and _ag_label_edge. These serve as parent tables for all subsequently created vertex and edge labels. The following queries demonstrate how to list all vertex and edge labels across all graphs.

-- Before creating any vertex label
SELECT * FROM ag_catalog.ag_label;

       name       | graph | id | kind |          relation          |        seq_name         
------------------+-------+----+------+----------------------------+-------------------------
 _ag_label_vertex | 68484 |  1 | v    | new_graph._ag_label_vertex | _ag_label_vertex_id_seq
 _ag_label_edge   | 68484 |  2 | e    | new_graph._ag_label_edge   | _ag_label_edge_id_seq
(2 rows)

-- Create a new vertex label
SELECT create_vlabel('new_graph', 'Person');
NOTICE:  VLabel "Person" has been created
 create_vlabel 
---------------

(1 row)

-- After creating the vertex label
SELECT * FROM ag_catalog.ag_label;
       name       | graph | id | kind |          relation          |        seq_name         
------------------+-------+----+------+----------------------------+-------------------------
 _ag_label_vertex | 68484 |  1 | v    | new_graph._ag_label_vertex | _ag_label_vertex_id_seq
 _ag_label_edge   | 68484 |  2 | e    | new_graph._ag_label_edge   | _ag_label_edge_id_seq
 Person           | 68484 |  3 | v    | new_graph."Person"         | Person_id_seq
(3 rows)

Calling create_vlabel() creates a new table new_graph."<label>" within the graph’s namespace. The same mechanism applies for create_elabel().

Tables are created automatically when inserting vertices or edges via Cypher.

-- Create two vertices and one edge
SELECT * FROM cypher('new_graph', $$
CREATE (:Person {name: 'Daedalus'})-[:FATHER_OF]->(:Person {name: 'Icarus'})
$$) AS (a agtype);
 a 
---
(0 rows)

-- Verify newly created tables
SELECT * FROM ag_catalog.ag_label;
       name       | graph | id | kind |          relation          |        seq_name         
------------------+-------+----+------+----------------------------+-------------------------
 _ag_label_vertex | 68484 |  1 | v    | new_graph._ag_label_vertex | _ag_label_vertex_id_seq
 _ag_label_edge   | 68484 |  2 | e    | new_graph._ag_label_edge   | _ag_label_edge_id_seq
 Person           | 68484 |  3 | v    | new_graph."Person"         | Person_id_seq
 FATHER_OF        | 68484 |  4 | e    | new_graph."FATHER_OF"      | FATHER_OF_id_seq
(4 rows)

Note!
Do not execute DML or DDL commands inside namespaces reserved for graphs.

Note!
Index and constraint limitations on label tables in YMatrix AGE:
Label tables use DISTRIBUTED RANDOMLY, which prohibits UNIQUE indexes and PRIMARY KEY constraints. As a result, duplicate data cannot be prevented at the storage layer via uniqueness enforcement.

CREATE UNIQUE INDEX idx ON graph_name."TestIdx"(properties);
-- ERROR: UNIQUE and DISTRIBUTED RANDOMLY are incompatible

ALTER TABLE graph_name."TestIdx" ADD PRIMARY KEY (id);
-- ERROR: PRIMARY KEY and DISTRIBUTED RANDOMLY are incompatible

To prevent duplicates, enforce uniqueness at the application layer or using Cypher logic — for example, by using MERGE instead of CREATE.

To remove a label when no longer needed, use drop_label():

SELECT drop_label(graph_name, label_name, true /* required */);

← Previous

Overview

Query Format

English Русский 简体中文