Apache AGE's ListGraphid

Greetings!

In today's post, we are going to explain a simple yet vital structure in Apache AGE, 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 file, which resides in the Apache AGE source code, and it looks like this:

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:

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:

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