Introduction
We've seen the various ways we can install the apache age extension on our local machine. Now we need to understand the query format used in age, how to create a graph and delete a graph.
Query Format
AGE uses the format cypher(graph_name, query_string, parameters). The cypher() function is a function in the ag_catalog (ag_catalog is a schema that is loaded when you LOAD 'age') that returns a postgres SETOF records. As seen, the cypher() function takes in 3 arguments:
- graph_name: Basically the name of the graph in the database (that has already been created) that you want to work on. We'll see how to create a graph and delete a graph in a minute
- query_string: This takes a string of queries that allows you to perform operations on the graph. This string of queries is a special type of language called Cypher Query Language.
- parameters: An optional map of parameters used for Prepared Statements. Default is NULL.
Creating and Deleting graphs
To use a graph_name in the cypher() function we talked about above we need to first create a graph. Creating a graph simply creates a schema in the database in which all the graph objects(vertices, edges, labels etc...) are stored.
To create a graph we use the create_graph() function from the ag_catalog schema/namespace which takes an argument which is the graph_name, this creates a schema with the graph_name and also some boiler plates objects in the created schema. Deleting a graph simply requires using the function drop_graph() also defined in the ag_catalog, which takes 2 arguments: graph_name, cascade.
The cascade argument takes a boolean value of either true or false on whether to delete labels and data that depends on the graph. According to the docs it's recommended to keep this as true.
Now let's create our first graph.
1. Listing out the schemas/namespace present in the database:
postgresDB=# SELECT schema_name
postgresDB-# FROM information_schema.schemata;
schema_name
--------------------
ag_catalog
information_schema
public
pg_catalog
pg_toast_temp_1
pg_temp_1
pg_toast
(7 rows)
Here we see ag_catalog is present, ag_catalog is the namespace in which all the main age functions are stored. So to use any of the above function we'll need to make sure ag_catalog is present.
2. Creating a graph
To create a graph test_graph we'll run the query SELECT * FROM ag_catalog.create_graph('test_graph')
postgresDB=# SELECT * FROM ag_catalog.create_graph('test_graph');
NOTICE: graph "test_graph" has been created
create_graph
--------------
(1 row)
postgresDB=#
Remember i said creating graph creates a namespace to store all the objects peculiar to the graph. To check if the graph was created we'll list our current shemas again.
postgresDB=# SELECT schema_name
FROM information_schema.schemata;
schema_name
--------------------
test_graph
ag_catalog
information_schema
public
pg_catalog
pg_toast_temp_1
pg_temp_1
pg_toast
(8 rows)
postgresDB=#
Now we see that our graph has been created.
3. Deleting a graph
Just like i said earlier, deleting a graph is as easy as simply calling the drop_graph() function. But we'll be passing in the true value for our second argument (cascade).
postgresDB=# SELECT * FROM ag_catalog.drop_graph('test_graph', true);
NOTICE: drop cascades to 2 other objects
DETAIL: drop cascades to table test_graph._ag_label_vertex
drop cascades to table test_graph._ag_label_edge
NOTICE: graph "test_graph" has been dropped
drop_graph
------------
(1 row)
postgresDB=#
Now we've deleted the test_graph, notice how there are also other two objects deleted as a result of setting cascade to true, if we didn't set it to true, we'll have to manually delete those objects.
Going back to our query format, the second arguments which is the query_string is usually embedded in a "$$" delimeter which is used to signify the beginning and end of the query. The last argument we won't worry to much about for now.
The basic query format goes like this
SELECT * FROM ag_catalog.cypher('graph_name', $$
"cypher query goes here"
$$) as (result agtype);
We'll talk more about agtype and cypher query language in the coming articles in this series
Now let's put all we've learned together and create a graph, run a simple query to return "hello world" on the graph and also delete the graph
postgresDB=# SELECT * FROM ag_catalog.create_graph('test_graph');
NOTICE: graph "test_graph" has been created
create_graph
--------------
(1 row)
postgresDB=# SELECT * FROM ag_catalog.cypher('test_graph', $$
RETURN "Hello World"
$$) as (result ag_catalog.agtype);
result
---------------
"Hello World"
(1 row)
postgresDB=# SELECT * FROM ag_catalog.drop_graph('test_graph', true);
NOTICE: drop cascades to 2 other objects
DETAIL: drop cascades to table test_graph._ag_label_vertex
drop cascades to table test_graph._ag_label_edge
NOTICE: graph "test_graph" has been dropped
drop_graph
------------
(1 row)
postgresDB=#
appending ag_catalog to every age function all the time can be pretty daunting, we can set the search_path to include ag_catalog, so by default it looks in the ag_catalog when a function is called.
postgresDB=# SET search_path = ag_catalog, "$user", public;
SET
postgresDB=# SELECT * FROM create_graph('test_graph');
NOTICE: graph "test_graph" has been created
create_graph
--------------
(1 row)
postgresDB=# SELECT * FROM cypher('test_graph', $$
RETURN "Hello World"
$$) as (result agtype);
result
---------------
"Hello World"
(1 row)
postgresDB=# SELECT * FROM drop_graph('test_graph', true);
This way is easier and cleaner.
Conclusion
We've been able to see the basic query format in age including how to create a graph, what happens when you create a graph, running a basic query in the graph and how to delete a graph. It's important to note that while providing the graph_name in any of the functions we've talked about today, graph name must be put in single quotes, double quotes might throw an error. In the coming articles we'll talk about different datatypes and cypher queries.
Top comments (0)