APACHE AGE: Getting Started Part 4(AGE Query Formats)
Published: 2023-06-26 19:32:02

## 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.