Apache AGE's ListGraphid
Tags: apacheage, postgres, apache, graphdatabase
Published: 2023-06-28 14:16:48

Greetings!

In today's post, we are going to explain a simple yet vital structure in [Apache AGE](https://age.apache.org/), the PostgreSQL extension for graph databases: the `ListGraphId` structure. The aim is to help you understand how it functions, why it is essential, and how you can iterate over it.

## What is the `ListGraphId` structure?

`ListGraphId` is a particular structure designed to store a list of nodes (vertices) in a graph. Each node is represented by a unique `graphid`, an `int64` identifier. 

The structure is defined in the [`age_graphid_ds.c`](https://github.com/apache/age/blob/fada9c9cbe348e10593b6647d3bdb5864a719a1b/src/backend/utils/adt/age_graphid_ds.c) file, which resides in the Apache AGE source code, and it looks like this:

```c
typedef struct ListGraphId
{
    GraphIdNode *head;
    GraphIdNode *tail;
    int64 size;
} ListGraphId;
```

In `ListGraphId`, `head` points to the first node of the list, `tail` points to the last node, and `size` represents the total number of nodes in the list.

## The `GraphIdNode` Structure

Before delving into `ListGraphId`, let's take a quick look at the `GraphIdNode` structure, which is the "node" of our `ListGraphId`. Here is its definition:

```c
typedef struct GraphIdNode
{
    graphid id;
    struct GraphIdNode *next;
} GraphIdNode;
```

In `GraphIdNode`, `id` is the unique identifier (`graphid`) of a graph node (vertex), and `next` is a pointer to the next node in the list. Simple, isn't it?

## Why `ListGraphId`?

You might wonder, why go through the trouble of creating a structure like `ListGraphId` when PostgreSQL has a `List` structure? The reason is quite straightforward. PostgreSQL's `List` structure does not directly support `int64` data types, which are used for graph vertex identifiers (`graphid`). Therefore, `ListGraphId` was created as a more suitable alternative for handling lists of `graphid`.

## Iterating over `ListGraphId`

Now let's dive into how to iterate over `ListGraphId`. Given its linked-list nature, we can employ a basic linked-list traversal technique.

Here is a simple function that prints all `graphid` in a `ListGraphId`:

```c
void print_graph_ids(ListGraphId* listgraphid)
{
    GraphIdNode* curr_node;
    
    /* Start from the head node */
    for(curr_node = listgraphid->head; 
        curr_node != NULL; 
        curr_node = curr_node->next)
    {
        printf("%lld\n", curr_node->id);
    }
}
```

In the `print_graph_ids` function, we start with the `head` node of the `ListGraphId` and follow the `next` pointers until we reach the end of the list (`NULL`). At each node, we print out the `graphid`.

And voila, you've successfully iterated over a `ListGraphId` structure.

## Wrapping Up

Understanding the `ListGraphId` structure and how to iterate over it is a crucial step for anyone looking to dive deeper into Apache AGE's internals or working on more advanced graph database manipulations with this extension.

This simple yet effective data structure forms the basis for more advanced operations and techniques in Apache AGE. In the coming blog posts, we'll explore more about these features and continue our journey into graph databases.

---

I hope this clarifies the `ListGraphId` structure's purpose and usage in Apache AGE. Do you have any questions or is there anything else you want to know? Please feel free to comment below.

___

Check Apache AGE: https://age.apache.org/.

Overview — Apache AGE master documentation: https://age.apache.org/age-manual/master/intro/overview.html.

GitHub - apache/age: https://github.com/apache/age