Для создания графа используйте функцию create_graph из пространства имён ag_catalog.

Суперпользователь может предоставлять права на отдельные существующие графы обычным пользователям (в следующем примере предоставляются права на граф graph1 пользователю db_user):

GRANT USAGE ON SCHEMA graph1 TO db_user;
GRANT ALL PRIVILEGES ON SCHEMA graph1 TO db_user;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA graph1 TO db_user;
GRANT ALL PRIVILEGES ON TABLE graph1._ag_label_vertex TO db_user;

Для удаления графа используйте функцию drop_graph из пространства имён ag_catalog.

При создании графов с помощью apache_age для каждого отдельного графа создаётся пространство имён Postgres Pro. Имена и пространства имён созданных графов можно увидеть в таблице ag_graph пространства имён ag_catalog:

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)

После создания графа в его пространстве имён будут созданы две таблицы для хранения вершин и рёбер: _ag_label_vertex и _ag_label_edge. Они будут родительскими таблицами для любой новой метки вершины или ребра. В запросе ниже показано, как получить метки рёбер и вершин для всех графов в базе данных.

-- До создания новой метки вершины.
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)

-- Создание новой метки вершины.
SELECT create_vlabel('new_graph', 'Person');
NOTICE:  VLabel 'Person' has been created
 create_vlabel
---------------

(1 row)

-- После создания новой метки вершины.
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)

При создании метки вершины функцией create_vlabel() в пространстве имён new_graph создаётся новая таблица: new_graph.'метка'. То же самое происходит при создании меток рёбер функцией create_elabel(). При создании вершин и рёбер с помощью языка Cypher эти таблицы создаются автоматически.

-- Создание двух вершин и одного ребра.
SELECT * FROM cypher('new_graph', $$
CREATE (:Person {name: 'Daedalus'})-[:FATHER_OF]->(:Person {name: 'Icarus'})
$$) AS (a agtype);
 a
---
(0 rows)

-- Вывод новых созданных таблиц.
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)

Язык Cypher нельзя использовать как часть выражения, вместо этого следует использовать подзапрос. Для получения дополнительной информации о том, как использовать Cypher-запросы с выражениями, обратитесь к разделу Расширенные Cypher-запросы.

Вызывать язык Cypher в качестве независимого столбца в предложении SELECT не допускается. Однако Cypher может использоваться в качестве условного выражения.

SELECT
    cypher('graph_name', $$
         MATCH (v:Person)
         RETURN v.name
     $$);

ERROR:  cypher(...) in expressions is not supported
LINE 3:     cypher('graph_name', $$
            ^
HINT:  Use subquery instead if possible.

Сущность имеет уникальную, сравниваемую идентичность, которая определяет, равны ли две сущности.

Сущности присваивается набор свойств, каждое из которых уникально идентифицируется в наборе соответствующими ключами свойств.

{id:1; label: 'label_name'; properties: {prop1: value1, prop2: value2}}::vertex

Приведение ассоциативного массива к вершине:

SELECT *
FROM cypher('graph_name', $$
    WITH {id: 0, label: 'label_name', properties: {i: 0}}::vertex as v
    RETURN v
$$) AS (v agtype);

                                v
------------------------------------------------------------------
 {"id": 0, "label": "label_name", "properties": {"i": 0}}::vertex
(1 row)

Ребро — это сущность, которая представляет собой направленное соединение между двумя узлами: исходным узлом и целевым узлом. Исходящее ребро — это направленная связь с точки зрения исходного узла. Входящее ребро — это направленная связь с точки зрения целевого узла. Ребру присваивается только один тип ребра.

{id: 3; startid: 1; endid: 2; label: 'edge_label' properties{prop1: value1, prop2: value2}}::edge

Приведение ассоциативного массива к ребру:

SELECT *
FROM cypher('graph_name', $$
    WITH {id: 2, start_id: 0, end_id: 1, label: 'label_name', properties: {i: 0}}::edge as e
    RETURN e
$$) AS (e agtype);

                                             e
--------------------------------------------------------------------------------------------
 {"id": 2, "label": "label_name", "end_id": 1, "start_id": 0, "properties": {"i": 0}}::edge
(1 row)

Путь — это серия чередующихся вершин и рёбер. Путь должен начинаться с вершины и иметь хотя бы одно ребро.

Приведение списка к пути:

SELECT *
FROM cypher('graph_name', $$
    WITH [{id: 0, label: 'label_name_1', properties: {i: 0}}::vertex,
            {id: 2, start_id: 0, end_id: 1, label: 'edge_label', properties: {i: 0}}::edge,
           {id: 1, label: 'label_name_2', properties: {}}::vertex
           ]::path as p
    RETURN p
$$) AS (p agtype);

                                                                                                                  p
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 [{"id": 0, "label": "label_name_1", "properties": {"i": 0}}::vertex, {"id": 2, "label": "edge_label", "end_id": 1, "start_id": 0, "properties": {"i": 0}}::edge, {"id": 1, "label": "label_name_2", "properties": {}}::vertex]::path
(1 row)

Спецификация openCypher содержит четыре различные концепции, связанные с равенством и упорядочиванием:

Операторы сравнения должны работать так, как и ожидается — равенство и сопоставимость. Но в то же время им необходимо разрешить сортировку данных в столбцах — эквивалентность и упорядочиваемость.

К сожалению, в Postgres Pro может оказаться невозможным реализовать отдельные операторы сравнения для операций сравнения и равенства, а также операций эквивалентности и упорядочиваемости для одного и того же запроса. Поэтому в apache_age отдаётся приоритет эквивалентности и упорядочиваемости над равенством и сопоставимостью, чтобы обеспечить упорядочивание выходных данных.

Упорядочивание различных типов agtype при использовании <, <=, >, >= от наименьшего значения к наибольшему:

SELECT * FROM cypher('graph_name', $$
CREATE (:Person {name: 'John'}),
       (:Person {name: 'Jeff'}),
       (:Person {name: 'Joan'}),
       (:Person {name: 'Bill'})
$$) AS (result agtype);

Приоритет операторов в apache_age представлен ниже:

Для вычисления агрегированных данных в Cypher предусмотрено агрегирование, аналогичное GROUP BY в SQL.

Агрегатные функции принимают набор значений и вычисляют по ним агрегированное значение. Например, avg() вычисляет среднее значение нескольких числовых значений, а min() находит наименьшее числовое или строковое значение в наборе значений. Ниже указывается, что агрегатная функция работает с набором значений, при этом имеется в виду, что они являются результатом применения внутреннего выражения (например, n.age) ко всем записям в пределах одной группы агрегирования.

Агрегирование можно выполнять по всем совпадающим подграфам или дополнительно разделять путём введения ключей группировки. Это неагрегатные выражения, которые используются для группировки значений, входящих в агрегатные функции.

Допустим, что у нас есть следующий оператор RETURN:

SELECT * FROM cypher('graph_name', $$
    MATCH (v:Person)
    RETURN v.name, count(*)
$$) as (grouping_key agtype, count agtype);

 grouping_key | count
--------------+-------
 "A"          | 1
 "D"          | 2
 "B"          | 1
 "C"          | 1
(4 rows)

У нас есть два возвращаемых выражения: grouping_key и count(*). Первое, grouping_key, не является агрегатной функцией и поэтому будет ключом группировки. Последнее, count(*), представляет собой агрегатное выражение. Соответствующие подграфы будут разделены на разные группы в зависимости от ключа группировки. Затем для этих групп будет запущена агрегатная функция, вычисляющая агрегированное значение для каждой группы.

Чтобы для сортировки набора результатов использовать агрегирование, его следует включить в предложение RETURN, которое будет использоваться в ORDER BY.

SELECT *
FROM cypher('graph_name', $$
    MATCH (me:Person)-[]->(friend:Person)
    RETURN count(friend), me
    ORDER BY count(friend)
$$) as (friends agtype, me agtype);

В агрегировании DISTINCT (т. е. в форме aggr(DISTINCT expr)) список агрегированных значений представляет собой список значений-кандидатов, из которого удалены все значения null. Кроме того, при агрегировании DISTINCT только одно из всех эквивалентных значений-кандидатов включается в список агрегированных значений, т. е. дубликаты при эквивалентности удаляются.

Оператор DISTINCT работает совместно с агрегированием. Он используется для того, чтобы сделать все значения уникальными перед их использованием в агрегатной функции.

SELECT *
FROM cypher('graph_name', $$
    MATCH (v:Person)
    RETURN count(DISTINCT v.eyes), count(v.eyes)
$$) as (distinct_eyes agtype, eyes agtype);

 distinct_eyes | eyes
---------------+------
 2             | 3
(1 row)

При использовании операторов, не требующих от пользователя указания ключей группировки для запроса, Cypher может неоднозначно воспринимать, что именно следует квалифицировать как ключ группировки.

SELECT * FROM cypher('graph_name', $$
CREATE (:L {a: 1, b: 2, c: 3}),
       (:L {a: 2, b: 3, c: 1}),
       (:L {a: 3, b: 1, c: 2})
$$) as (a agtype);

SELECT * FROM cypher('graph_name', $$
    MATCH (x:L)
    RETURN x.a + count(*) + x.b + count(*) + x.c
$$) as (a agtype);

ERROR:  'x' must be either part of an explicitly listed key or used inside an aggregate function
LINE 3: RETURN x.a + count(*) + x.b + count(*) + x.c

SELECT * FROM cypher('graph_name', $$
    MATCH (x:L)
    RETURN (x.a + x.b + x.c) + count(*) + count(*), x.a + x.b + x.c
$$) as (count agtype, key agtype);

count  | key
-------+-----
 12    | 6
(1 row)

SELECT * FROM cypher('graph_name', $$
    MATCH (x:L)
    RETURN x.a + count(*) + x.b + count(*) + x.c, x.a, x.b, x.c
$$) as (count agtype, a agtype, b agtype, c agtype);

 count | a | b | c
-------+---+---+---
 10    | 3 | 1 | 2
 10    | 2 | 3 | 1
 10    | 1 | 2 | 3
(3 rows)

SELECT * FROM cypher('graph_name', $$
    MATCH (x:L)
    RETURN count(*) + count(*) + x.a + x.b + x.c, x
$$) as (count agtype, key agtype);

 count |                                          key
-------+----------------------------------------------------------------------------------------
 8     | {"id": 1407374883553283, "label": "L", "properties": {"a": 3, "b": 1, "c": 2}}::vertex
 8     | {"id": 1407374883553281, "label": "L", "properties": {"a": 1, "b": 2, "c": 3}}::vertex
 8     | {"id": 1407374883553282, "label": "L", "properties": {"a": 2, "b": 3, "c": 1}}::vertex
(3 rows)

SELECT * FROM cypher('graph_name', $$
    MATCH (x:L)
    WITH count(*) + count(*) + x.a + x.b + x.c as column, x
    RETURN column
$$) as (a agtype);

 a
---
 8
 8
 8
(3 rows)

Ниже приведены подробные сведения о функциях для загрузки вершин и рёбер из файла.

Функция load_labels_from_file используется для загрузки вершин из CSV-файлов.

load_labels_from_file('имя_графа',
                      'имя_метки',
                      'путь_к_файлу')

При добавлении четвёртого параметра пользователь может исключить поле id. Следует использовать, если в файле нет поля id.

load_labels_from_file('имя_графа',
                      'имя_метки',
                      'путь_к_файлу',
                      false)

Функцию load_edges_from_file можно использовать для загрузки рёбер из CSV-файла. Структура файла представлена ниже.

load_edges_from_file('имя_графа',
                      'имя_метки',
                      'путь_к_файлу');

Ниже описывается структура CSV-файлов для вершин и рёбер.

CSV-файл для узлов должен иметь следующий вид:

Подобным образом, CSV-файл для рёбер должен иметь следующий вид:

Когда соединение между двумя вершинами имеет переменную длину, список рёбер, образующих соединение, можно вернуть, используя следующее соединение.

Вместо описания длинного пути с последовательностью описаний множества вершин и рёбер в шаблоне многие рёбра (и промежуточные вершины) можно описать, указав длину в описании ребра в шаблоне.

(u)-[*2]->(v)

Такой шаблон, описывающий направленный вправо путь из трёх вершин и двух рёбер, можно переписать так:

(u)-[]->()-[]->(v)

Также можно указать длину диапазона:

(u)-[*3..5]->(v)

Что эквивалентно следующему:

(u)-[]->()-[]->()-[]->(v) and
(u)-[]->()-[]->()-[]->()-[]->(v) and
(u)-[]->()-[]->()-[]->()-[]->()-[]->(v)

В приведённом выше примере для пути задавалась как нижняя, так и верхняя граница количества рёбер (и вершин) между u и v. Можно исключить одно или оба эти значения связывания.

(u)-[*3..]->(v)

Возвращает все пути между u и v, включающие три или более рёбер.

(u)-[*..5]->(v)

Возвращает все пути между u и v, включающие пять или менее рёбер.

(u)-[*]->(v)

Возвращает все пути между u и v.

SELECT * FROM cypher('graph_name', $$
    MATCH p = (actor {name: 'Willam Dafoe'})-[:ACTED_IN*2]-(co_actor)
    RETURN relationships(p)
$$) as (r agtype);

                                                                               r
------------------------------------------------------------------------------------------------------------------------------------------------------------------
[{id: 0; label:"ACTED_IN"; properties: {role: "Green Goblin"}}::edge, {id: 1; label: "ACTED_IN; properties: {role: "Spiderman", actor: "Toby Maguire}}::edge]
[{id: 0; label:"ACTED_IN"; properties: {role: "Green Goblin"}}::edge, {id: 2; label: "ACTED_IN; properties: {role: "Spiderman", actor: "Andrew Garfield"}}::edge]
(2 rows)

Чтобы можно было фильтровать агрегированные результаты, они должны пройти через предложение WITH.

SELECT *
FROM cypher('graph_name', $$
    MATCH (david {name: 'David'})-[]-(otherPerson)-[]->()
    WITH otherPerson, count(*) AS foaf
    WHERE foaf > 1
    RETURN otherPerson.name
$$) as (name agtype);

  name
--------
"Anders"
(1 row)

Запрос вернёт имя человека, связанного с «David» более чем одним исходящим отношением.

Можно отсортировать результаты перед их передачей в collect, таким образом, получившийся список тоже будет отсортирован.

SELECT *
FROM cypher('graph_name', $$
    MATCH (n)WITH n
    ORDER BY n.name DESC LIMIT 3
    RETURN collect(n.name)
$$) as (names agtype);

         names
-------------------------
["Emil","David","Ceasar"]
(1 row)

Возвращается список из не более чем трёх имён людей в обратном порядке.

Можно сопоставить пути, ограничить их количество, а затем снова сопоставить, используя в качестве основы эти пути, а также любое количество подобных ограниченных поисков.

SELECT *
FROM cypher('graph_name', $$
    MATCH (n {name: 'Anders'})-[]-(m)WITH m
    ORDER BY m.name DESC LIMIT 1
    MATCH (m)-[]-(o)
    RETURN o.name
$$) as (name agtype);

  name
-------
"Anders"
"Bossman"
(2 rows)

Начиная с «Anders», находит все совпадающие узлы, упорядочивает их в алфавитном порядке и получает верхний результат, затем находит все узлы, связанные с этим верхним результатом, и возвращает их имена.

Чтобы вернуть узел, укажите его в операторе RETURN.

SELECT *
FROM cypher('graph_name', $$
    MATCH (n {name: 'B'})
    RETURN n
$$) as (n agtype);

                       n
---------------------------------------------------
{id: 0; label: '' properties: {name: 'B'}}::vertex
(1 row)

В примере возвращается узел.

Чтобы вернуть n рёбер, просто включите их в список RETURN.

SELECT *
FROM cypher('graph_name', $$
    MATCH (n)-[r:KNOWS]->()
    WHERE n.name = 'A'
    RETURN r
$$) as (r agtype);

                              r
-------------------------------------------------------------------
 {id: 2; startid: 0; endid: 1; label: 'KNOWS' properties: {}}::edge
(1 row)

В примере возвращается отношение.

Чтобы вернуть свойство, используйте разделитель-точку:

SELECT *
FROM cypher('graph_name', $$
    MATCH (n {name: 'A'})
    RETURN n.name
$$) as (name agtype);

 name
------
 'A'
(1 row)

Возвращается значение name свойства.

Если необходимо вернуть все вершины, рёбра и пути, соответствующие запросу, можно использовать символ *.

SELECT *
FROM cypher('graph_name', $$
    MATCH (a {name: 'A'})-[r]->(b)
    RETURN *
$$) as (a agtype, b agtype, r agtype);

                                             a                                                          |                                                                 b	                                                          |                                 r
--------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------
 {"id": 281474976710659, "label": "", "properties": {"age": 55, "name": "A", "happy": "Yes!"}}::vertex	| {"id": 1125899906842625, "label": "BLOCKS", "end_id": 281474976710660, "start_id": 281474976710659, "properties": {}}::edge	| {"id": 281474976710660, "label": "", "properties": {"name": "B"}}::vertex
 {"id": 281474976710659, "label": "", "properties": {"age": 55, "name": "A", "happy": "Yes!"}}::vertex	| {"id": 1407374883553281, "label": "KNOWS", "end_id": 281474976710660, "start_id": 281474976710659, "properties": {}}::edge	| {"id": 281474976710660, "label": "", "properties": {"name": "B"}}::vertex
(2 rows)

Возвращает две вершины и ребро, указанные в запросе.

Чтобы ввести заполнитель, состоящий из символов, которых нет в английском алфавите, переменную можно заключить в `, например:

SELECT *
FROM cypher('graph_name', $$
    MATCH (`This isn\'t a common variable`)
    WHERE `This isn\'t a common variable`.name = 'A'
    RETURN `This isn\'t a common variable`.happy
$$) as (happy agtype);

 happy
-------
 "Yes!"
(1 row)

Возвращается узел с именем «A».

Если имя поля должно отличаться от используемого выражения, можно переименовать его, изменив имя в определении списка столбцов.

SELECT *
FROM cypher('graph_name', $$
    MATCH (n {name: 'A'})
    RETURN n.name
$$) as (objects_name agtype);

 objects_name
-------------
 'A'
(1 row)

Возвращает свойство узла, но переименовывает поле.

Если неизвестно, существует ли свойство, будет считаться, что оно имеет значение null, если оно отсутствует.

SELECT *
FROM cypher('graph_name', $$
    MATCH (n)
    RETURN n.age
$$) as (age agtype);

 age
-----
 55
 NULL
(2 rows)

В этом запросе возвращается свойство, если оно существует, или null в противном случае.

В качестве возвращаемого элемента можно использовать любое выражение — литералы, предикаты, свойства, функции и всё прочее.

SELECT *
FROM cypher('graph_name', $$
    MATCH (a)
    RETURN a.age > 30, 'I\'m a literal', id(a)
$$) as (older_than_30 agtype, literal agtype, id agtype);

 older_than_30 | literal         | id
---------------+-----------------+----
 true          | 'I'm a literal' | 1
(1 row)

Возвращает предикат, литерал и вызов функции с параметром выражения шаблона.

DISTINCT извлекает только уникальные записи в зависимости от полей, выбранных для вывода.

SELECT *
FROM cypher('graph_name', $$
MATCH (a {name: 'A'})-[]->(b)
RETURN DISTINCT b
$$) as (b agtype);

                          b
----------------------------------------------------
 {id: 1; label: '' properties: {name: 'B'}}::vertex
(1 row)

Запрос возвращает узел с именем «B», но только один раз.

ORDER BY используется для сортировки вывода.

SELECT *
FROM cypher('graph_name', $$
    MATCH (n)
    WITH n.name as name, n.age as age
    ORDER BY n.name
    RETURN name, age
$$) as (name agtype, age agtype);

  name  | age
--------+-----
  "A"	  | 34
  "B"	  | 34
  "C"	  | 32
(3 rows)

Возвращаются узлы, отсортированные по имени.

Можно упорядочить значения по нескольким свойствам, указав каждую переменную в предложении ORDER BY. Cypher отсортирует результаты по первой указанной переменной и, если значения равны, перейдёт к следующему свойству в предложении ORDER BY и так далее.

SELECT *
FROM cypher('graph_name', $$
    MATCH (n)
    WITH n.name as name, n.age as age
    ORDER BY n.age, n.name
    RETURN name, age
$$) as (name agtype, age agtype);

  name  | age
--------+-----
  "C"	  | 32
  "A"	  | 34
  "B"	  | 34
(3 rows)

Возвращает узлы, отсортированные сначала по свойству возраста, а затем по имени.

Если добавить DESC[ENDING] после переменной для сортировки, сортировка будет выполнена в обратном порядке.

SELECT *
FROM cypher('graph_name', $$
    MATCH (n)
    WITH n.name AS name, n.age AS age
    ORDER BY n.name DESC
    RETURN name, age
$$) as (name agtype, age agtype);

  name  | age
--------+-----
  "C"	  | 32
  "B"	  | 34
  "A"	  | 34
(3 rows)

В примере возвращаются узлы, отсортированные по имени в обратном порядке.

При сортировке набора результатов по возрастанию значение null всегда будет находиться в конце набора результатов, а при сортировке по убыванию — в начале.

SELECT *
FROM cypher('graph_name', $$
    MATCH (n)
    WITH n.name AS name, n.age AS age, n.height AS height
    ORDER BY n.height
    RETURN name, age, height
$$) as (name agtype, age agtype, height agtype);

  name  | age | height
--------+-----+--------
  "A"	  | 34  | 170
  "C"	  | 32  | 185
  "B"	  | 34  | NULL
(3 rows)

Узлы возвращаются отсортированными по свойству длины, причём последним является узел без этого свойства.

Чтобы вернуть подмножество строк из результата, начиная сверху, используйте следующий синтаксис:

SELECT *
FROM cypher('graph_name', $$
    MATCH (n)
    RETURN n.name
    ORDER BY n.name
    SKIP 3
$$) as (names agtype);

 names
-------
 "D"
 "E"
(2 rows)

Возвращается свойство имени соответствующего узла n, с ограничением 3.

Чтобы вернуть подмножество строк из результата, начиная с середины, используйте следующий синтаксис:

SELECT *
FROM cypher('graph_name', $$
    MATCH (n)
    RETURN n.name
    ORDER BY n.name
    SKIP 1
    LIMIT 2
$$) as (names agtype);

 names
-------
 "B"
 "C"
(2 rows)

Возвращаются две вершины из середины.

Использование выражения с SKIP для возвращения подмножества строк.

SELECT *
FROM cypher('graph_name', $$
    MATCH (n)
    RETURN n.name
    ORDER BY n.name
    SKIP (3 * rand())+ 1
$$) as (a agtype);

 names
-------
 "C"
 "D"
 "E"
(3 rows)

Первые две вершины пропускаются, и в результате возвращаются только последние три.

Чтобы вернуть подмножество строк из результата, начиная сверху, используйте следующий синтаксис:

SELECT *
FROM cypher('graph_name', $$
    MATCH (n)RETURN n.name
    ORDER BY n.name
    LIMIT 3
$$) as (names agtype);

names
"A"
"B"
"C"
3 rows

Возвращается узел, и для него не существует свойство age.

LIMIT принимает любое выражение, результатом которого является положительное целое число, если это выражение не ссылается на какие-либо внешние переменные:

SELECT *
FROM cypher('graph_name', $$
    MATCH (n)
    RETURN n.name
    ORDER BY n.name
    LIMIT toInteger(3 * rand()) + 1
$$) as (names agtype);

 names
-------
 "A"
 "B"
(2 rows)

Возвращает от одного до трёх верхних элементов.

Предложение CREATE, за которым не следует другое предложение, является завершающим предложением. Когда Cypher-запрос заканчивается завершающим предложением, результаты вызова функции Cypher не возвращаются. Однако вызов Cypher-функции по-прежнему требует определения списка столбцов. Когда Cypher-запрос заканчивается завершающим узлом, задайте одно значение в определении списка столбцов: в этой переменной не будут возвращаться данные.

SELECT *
FROM cypher('graph_name', $$
    CREATE /* Create clause here, no following clause */
$$) as (a agtype);

 a
---
(0 rows)

Создать одну вершину можно с помощью следующего запроса.

SELECT *
FROM cypher('graph_name', $$
    CREATE (n)
$$) as (v agtype);

 v
---
(0 rows)

Этот запрос ничего не возвращает.

Можно создать нескольких вершин, разделив их запятыми.

SELECT *
FROM cypher('graph_name', $$
    CREATE (n), (m)
$$) as (v agtype);

   a
-------
(0 rows)

Для добавления метки при создании вершины используйте следующий синтаксис.

SELECT *
FROM cypher('graph_name', $$
    CREATE (:Person)
$$) as (v agtype);

   v
-------
(0 rows)

Этот запрос ничего не возвращает.

Можно создать вершину сразу с метками и свойствами.

SELECT *
FROM cypher('graph_name', $$
    CREATE (:Person {name: 'Andres', title: 'Developer'})
$$) as (n agtype);

   n
-------
(0 rows)

Этот запрос ничего не возвращает.

Можно создать и вернуть узел в рамках одного запроса, например:

SELECT *
FROM cypher('graph_name', $$
    CREATE (a {name: 'Andres'})
    RETURN a
$$) as (a agtype);

                                       a
--------------------------------------------------------------------------------
 {"id": 281474976710660, "label": "", "properties": {"name": "Andres"}}::vertex
(1 row)

Возвращается только что созданный узел.

Чтобы создать ребро между двумя вершинами, сначала нужно выполнить MATCH для двух вершин. После сопоставления узлов создайте между ними ребро.

SELECT *
FROM cypher('graph_name', $$
    MATCH (a:Person), (b:Person)
    WHERE a.name = 'Node A' AND b.name = 'Node B'
    CREATE (a)-[e:RELTYPE]->(b)
    RETURN e
$$) as (e agtype);

                              e
-----------------------------------------------------------------------
{id: 3; startid: 0, endid: 1; label: 'RELTYPE'; properties: {}}::edge
(1 row)

Запрос возвращает созданное ребро.

Свойства рёбер устанавливаются так же, как при создании вершин. Обратите внимание, что значения могут быть любым выражением.

SELECT *
FROM cypher('graph_name', $$
    MATCH (a:Person), (b:Person)
    WHERE a.name = 'Node A' AND b.name = 'Node B'
    CREATE (a)-[e:RELTYPE {name:a.name + '<->' + b.name}]->(b)
    RETURN e
$$) as (e agtype);

                                          e
---------------------------------------------------------------------------------------------------
 {id: 3; startid: 0, endid: 1; label: 'RELTYPE'; properties: {name: 'Node A<->Node B'}}::edge
(1 row)

Запрос в примере возвращает только что созданное ребро.

При использовании CREATE и шаблона будут созданы все части шаблонов, которые ещё не находятся в области видимости.

SELECT *
FROM cypher('graph_name', $$
    CREATE p = (andres {name:'Andres'})-[:WORKS_AT]->(neo)<-[:WORKS_AT]-(michael {name:'Michael'})
    RETURN p
$$) as (p agtype);

                     p
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 [{"id": 281474976710661, "label": "", "properties": {"name": "Andres"}}::vertex, {"id": 1407374883553282, "label": "WORKS_AT", "end_id": 281474976710662, "start_id": 281474976710661, "properties": {}}::edge, {"id": 281474976710662, "label": "", "properties": {}}::vertex, {"id": 1407374883553281, "label": "WORKS_AT", "end_id": 281474976710662, "start_id": 281474976710663, "properties": {}}::edge, {"id": 281474976710663, "label": "", "properties": {"name": "Michael"}}::vertex]::path
(1 row)

Этот запрос одновременно создаёт три узла и два отношения, назначает шаблон переменной пути и возвращает этот шаблон.

Для удаления вершины используйте предложение DELETE.

SELECT *
FROM cypher('graph_name', $$
    MATCH (v:Useless)
    DELETE v
$$) as (v agtype);

   v
-------
(0 rows)

В результате такого запроса удалятся вершины (с меткой «Useless»), у которых нет рёбер. Этот запрос ничего не возвращает.

В результате запроса с предложением MATCH собираются все узлы. Используйте параметр DETACH, чтобы сначала удалить рёбра вершины, а затем удалить саму вершину.

SELECT *
FROM cypher('graph_name', $$
    MATCH (v:Useless)
    DETACH DELETE v
$$) as (v agtype);

   v
-------
(0 rows)

Этот запрос ничего не возвращает.

Чтобы удалить ребро, используйте предложение MATCH для поиска нужных рёбер, а затем добавьте переменную в предложение DELETE.

SELECT *
FROM cypher('graph_name', $$
    MATCH (n {name: 'Andres'})-[r:KNOWS]->()
    DELETE r
$$) as (v agtype);

   v
-------
(0 rows)

Этот запрос ничего не возвращает.

С помощью предложения RETURN можно вернуть вершины, которые были удалены.

SELECT *
FROM cypher('graph_name', $$
    MATCH (n {name: 'A'})
    DELETE n
    RETURN n
$$) as (a agtype);

                                  a
---------------------------------------------------------------------------
 {"id": 281474976710659, "label": "", "properties": {"name": "A"}}::vertex
(1 rows)

Предложение SET, за которым не следует другое предложение, является завершающим предложением. Когда Cypher-запрос заканчивается завершающим предложением, результаты вызова функции Cypher не возвращаются. Однако вызов Cypher-функции по-прежнему требует определения списка столбцов. Когда Cypher-запрос заканчивается завершающим узлом, задайте одно значение в определении списка столбцов: в этой переменной не будут возвращаться данные.

Чтобы установить свойство узла или отношения, используйте SET.

SELECT *
FROM cypher('graph_name', $$
   MATCH (v {name: 'Andres'})
   SET v.surname = 'Taylor'
$$) as (v agtype);

   v
-------
(0 rows)

Запрос возвращает только что изменённый узел.

Создать одну вершину можно с помощью следующего запроса:

SELECT *
FROM cypher('graph_name', $$
    MATCH (v {name: 'Andres'})
    SET v.surname = 'Taylor'
    RETURN v
$$) as (v agtype);

                                                  v
-----------------------------------------------------------------------------------------------------
 {id: 3; label: 'Person'; properties: {surname:"Taylor", name:"Andres", age:36, hungry:true}}::vertex
(1 row)

Запрос возвращает только что изменённую вершину.

Обычно свойство удаляется с помощью команды REMOVE, но иногда бывает удобно сделать это с помощью команды SET. Одним из примеров является ситуация, когда свойство получено из параметра.

SELECT *
FROM cypher('graph_name', $$
    MATCH (v {name: 'Andres'})
    SET v.name = NULL
    RETURN v
$$) as (v agtype);

                                         v
---------------------------------------------------------------------------------------
 {id: 3; label: 'Person'; properties: {surname:"Taylor", age:36, hungry:true}}::vertex
(1 row)

Запрос возвращает узел, и свойство name теперь отсутствует.

Если нужно задать несколько свойств в рамках одного запроса, разделите их запятыми.

SELECT *
FROM cypher('graph_name', $$
MATCH (v {name: 'Andres'})
SET v.position = 'Developer', v.surname = 'Taylor'
RETURN v
$$) as (v agtype);

                                                    v
------------------------------------------------------------------------------------------------------------------------------
{"id": 281474976710661, "label": "", "properties": {"name": "Andres", "surname": "Taylor", "position": "Developer"}}: :vertex
(1 row)

Нет никаких ограничений на использование Cypher с CTE (общими табличными выражениями).

WITH graph_query as (
    SELECT *
        FROM cypher('graph_name', $$
        MATCH (n)
        RETURN n.name, n.age
    $$) as (name agtype, age agtype)
)
SELECT * FROM graph_query;

 name      | age
-----------+-----
 "Andres"  | 36
 "Tobias"  | 25
 "Peter"   | 35
(3 rows)

Cypher-запрос может быть частью предложения JOIN.

SELECT id,
    graph_query.name = t.name as names_match,
    graph_query.age = t.age as ages_match
FROM schema_name.sql_person AS t
JOIN cypher('graph_name', $$
        MATCH (n:Person)
        RETURN n.name, n.age, id(n)
$$) as graph_query(name agtype, age agtype, id agtype)
ON t.person_id = graph_query.id;

 id | names_match | ages_match
 ---+-------------+------------
 1  | True        | True
 2  | False       | True
 3  | True        | False
(3 rows)

Cypher нельзя использовать в выражениях, запрос должен существовать в предложении FROM запроса. Однако если запрос Cypher используется в подзапросе, он будет действовать как любой запрос в стиле SQL.

SELECT t.name FROM schema_name.sql_person AS t
where t.name = (
    SELECT a
    FROM cypher('graph_name', $$
          MATCH (v)
        RETURN v.name
    $$) as (name varchar(50))
    ORDER BY name
    LIMIT 1);

   name   | age
----------+-----
 "Andres" | 36
(1 rows)

SELECT t.name, t.age FROM schema_name.sql_person as t
where t.name in (
    SELECT *
    FROM cypher('graph_name', $$
        MATCH (v:Person)
        RETURN v.name
    $$) as (a agtype));

  name     | age
-----------+-----
 "Andres"  | 36
 "Tobias"  | 25
 "Peter"   | 35
(3 rows)

SELECT t.name, t.age
FROM schema_name.sql_person as t
WHERE EXISTS (
    SELECT *
    FROM cypher('graph_name', $$
      MATCH (v:Person)
        RETURN v.name, v.age
    $$) as (name agtype, age agtype)
    WHERE name = t.name AND age = t.age
);

   name    | age
-----------+-----
 "Andres"  | 36
 "Tobias"  | 25
 "Peter"   | 35
(3 rows)

SELECT graph_1.name, graph_1.age, graph_2.license_number
FROM cypher('graph_1', $$
    MATCH (v:Person)
    RETURN v.name, v.age
$$) as graph_1(col_1 agtype, col_2 agtype, col_3 agtype)
JOIN cypher('graph_2', $$
    MATCH (v:Doctor)
    RETURN v.name, v.license_number
$$) as graph_2(name agtype, license_number agtype)
ON graph_1.name = graph_2.name

   name    | age | license_number
-----------+-----+----------------
 "Andres"  | 36  | 1234567890
(1 rows)

Cypher может выполнить запрос на чтение внутри подготовленного оператора. При использовании параметров с хранимыми процедурами SQL-параметр должен быть помещён в вызов функции Cypher. За более подробной информацией обратитесь к разделу Формат запросов apache_age.

Параметры в Cypher используются в таком формате: «$» и идентификатор. В отличие от параметров Postgres Pro, параметры Cypher начинаются с буквы, за которой следует буквенно-цифровая строка произвольной длины. Пример: $имя_параметра

Использование подготовленных операторов в Cypher является расширением системы хранимых процедур Postgres Pro. Используйте предложение PREPARE, чтобы создать запрос с вызовом функции Cypher. Не размещайте параметры стиля Postgres Pro в вызове Cypher-запроса, вместо этого поместите параметры Cypher в запрос, а параметр Postgres Pro — в качестве третьего аргумента в вызове функции Cypher.

PREPARE cypher_stored_procedure(agtype) AS
SELECT *
FROM cypher('expr', $$
    MATCH (v:Person)
    WHERE v.name = $name //параметр Cypher
    RETURN v
$$, $1) //An SQL Parameter must be placed in the Cypher function call
AS (v agtype);

При выполнении подготовленного оператора поместите значение типа agtype map со значениями параметров туда, где находится параметр Postgres Pro в вызове функции Cypher. Значение должно иметь тип agtype map, иначе возникнет ошибка, а также следует исключить $ в именах параметров.

EXECUTE cypher_prepared_statement('{'name': 'Tobias'}');

Команды Cypher можно без ограничений выполнять в функциях PL/pgSQL.

SELECT *
FROM cypher('imdb', $$
    CREATE (toby:actor {name: 'Toby Maguire'}),
        (tom:actor {name: 'Tom Holland'}),
        (willam:actor {name: 'Willam Dafoe'}),
        (robert:actor {name: 'Robert Downey Jr'}),
        (spiderman:movie {title: 'Spiderman'}),
        (no_way_home:movie {title: 'Spiderman: No Way Home'}),
        (homecoming:movie {title: 'Spiderman: Homecoming'}),
        (ironman:movie {title: 'Ironman'}),
        (tropic_thunder:movie {title: 'Tropic Thunder'}),
        (toby)-[:acted_in {role: 'Peter Parker', alter_ego: 'Spiderman'}]->(spiderman),
        (willam)-[:acted_in {role: 'Norman Osborn', alter_ego: 'Green Goblin'}]->(spiderman),
        (toby)-[:acted_in {role: 'Toby Maguire'}]->(tropic_thunder),
        (robert)-[:acted_in {role: 'Kirk Lazarus'}]->(tropic_thunder),
        (robert)-[:acted_in {role: 'Tony Stark', alter_ego: 'Ironman'}]->(homecoming),
        (tom)-[:acted_in {role: 'Peter Parker', alter_ego: 'Spiderman'}]->(homecoming),
        (tom)-[:acted_in {role: 'Peter Parker', alter_ego: 'Spiderman'}]->(no_way_home),
        (toby)-[:acted_in {role: 'Peter Parker', alter_ego: 'Spiderman'}]->(no_way_home),
        (willam)-[:acted_in {role: 'Norman Osborn', alter_ego: 'Green Goblin'}]->(no_way_home)
$$) AS (a agtype);

Пример создания функции показан ниже.

CREATE OR REPLACE FUNCTION get_all_actor_names()
RETURNS TABLE(actor agtype)
LANGUAGE plpgsql
AS $BODY$
BEGIN
    LOAD 'age';
    SET search_path TO ag_catalog;

    RETURN QUERY
    SELECT *
    FROM ag_catalog.cypher('imdb', $$
        MATCH (v:actor)
        RETURN v.name
    $$) AS (a agtype);
END
$BODY$;

Выполните запрос:

SELECT * FROM get_all_actor_names();

       actor
--------------------
 "Toby Maguire"
 "Tom Holland"
 "Willam Dafoe"
 "Robert Downey Jr"
(4 rows)

CREATE OR REPLACE FUNCTION get_actors_who_played_role(role agtype)
RETURNS TABLE(actor agtype, movie agtype)
LANGUAGE plpgsql
AS $function$
DECLARE sql VARCHAR;
BEGIN
        load 'age';
        SET search_path TO ag_catalog;

        sql := format('
        SELECT *
        FROM cypher(''imdb'', $$
            MATCH (actor)-[:acted_in {role: %s}]->(movie:movie)
            RETURN actor.name, movie.title
        $$) AS (actor agtype, movie agtype);
    ', role);

        RETURN QUERY EXECUTE sql;

END
$function$;

SELECT * FROM get_actors_who_played_role('"Peter Parker"');

     actor      |          movie
----------------+--------------------------
 "Toby Maguire" | "Spiderman: No Way Home"
 "Toby Maguire" | "Spiderman"
 "Tom Holland"  | "Spiderman: Homecoming"
 "Tom Holland"  | "Spiderman: No Way Home"
(4 rows)

Расширение apache_age не поддерживает использование языка SQL непосредственно в Cypher-запросах. Однако с помощью пользовательских функций можно писать SQL-запросы и вызывать их командами Cypher.

Создание функции:

CREATE OR REPLACE FUNCTION public.get_event_year(name agtype) returns agtype AS $$
    SELECT year::agtype
    FROM history AS h
    WHERE h.event_name = name::text
    LIMIT 1;
$$ LANGUAGE sql;

SELECT * FROM cypher('graph_name', $$
    MATCH (e:event)
    WHERE e.year < public.get_event_year(e.name)
    RETURN e.name
$$) as (n agtype);

        n
-------------------
 "Apache Con 2021"
(1 row)